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: 557ee782b674 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.common import CurrentUser 15from ...types.system import SystemAccessToken 16from ...types.tasks import Task, TaskEnsureResult 17from ...types.threads import Thread 18from ...types.users import User, UserInvite, UserSSHKey 19 20 21class UserSshKeyCreateInput(TypedDict): 22 "Register an SSH public key" 23 24 label: str 25 "A label such as `Work laptop`." 26 public_key: str 27 "One `ssh-ed25519 <base64>` public key without options or a comment." 28 29 30class UserTaskCreateInputTask(TypedDict, total=False): 31 description: str | None 32 "Optional long-form description or notes for the task. Supports plain text." 33 due_date: datetime | None 34 "Date and time by which the task should be completed (ISO 8601). Omit to create the task without a due date." 35 epic: str | None 36 "Optional free-form grouping label." 37 id: str | None 38 "Optional caller-generated task public ID (`tsk_...`). Persist it before creating a task when creation must survive a lost response. An existing ID returns 409 without modifying the task; read the task by ID to reconcile. Omit for a server-generated ID." 39 links: dict[str, Any] | None 40 "Arbitrary key-value map of named URLs or references associated with the task (e.g. external ticket links)." 41 metadata: dict[str, Any] | None 42 "Arbitrary key-value map for storing application-specific data alongside the task. Omit to create the task with no metadata." 43 name: Required[str] 44 "Human-readable title for the task." 45 owner_agent: str | None 46 "ID of the agent to assign as owner (`agi_...`). Mutually exclusive with `owner_user`; omit to leave the task unassigned." 47 owner_user: str | None 48 "ID of the user to assign as owner (`usr_...`). Mutually exclusive with `owner_agent`; omit to leave the task unassigned." 49 parent: str | None 50 "Create this task as a subtask of an existing top-level task (`tsk_...`). Subtasks nest exactly one level." 51 priority: int | None 52 "Priority level from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when omitted." 53 project_id: str | None 54 "Optional project ID (`prj_...`). Pass null to clear it." 55 source_id: str | None 56 "Source object identity (for example `ArchAstro/firstlanding`)." 57 source_scope: str | None 58 "Container of the work this task is about (for example `github.com`). Must be supplied with `source_type` and `source_id`." 59 source_type: str | None 60 "Kind of source object (for example `repository`)." 61 status: str | None 62 'Initial status for the task. One of `"open"`, `"in_progress"`, `"in_review"`, `"paused"`, `"failed"`, `"superseding"`, `"done"`, or `"cancelled"`. Defaults to `"open"` when omitted.' 63 tags: list[str] | None 64 "Labels for grouping and filtering (max 20, each up to 40 characters). Stored canonically: lowercase, trimmed, de-duplicated." 65 target_binary: str | None 66 "Binary that must run this work, as a lowercase identifier of 1-64 characters (letters, digits, `.`, `_`, `-`; for example `my-cli`). Must be supplied with `target_version`." 67 target_version: str | None 68 "Minimum semantic version of `target_binary` that can run this work (`MAJOR.MINOR.PATCH` with optional prerelease and build, no leading `v`). Must be supplied with `target_binary`." 69 thread: str | None 70 "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." 71 72 73class UserTaskCreateInput(TypedDict, total=False): 74 "Create a task for an owner" 75 76 agent: str | None 77 "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." 78 org: str | None 79 "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." 80 task: Required[UserTaskCreateInputTask] 81 "Attributes for the task to create. `name` is required; all other fields are optional." 82 team: str | None 83 "Team ID (`tem_...`). The task will be owned by this team." 84 85 86class UserTaskBySourceInput(TypedDict, total=False): 87 "Find or create a task by source" 88 89 agent: str | None 90 "Explicit acting agent for privileged callers." 91 description: str | None 92 "Initial task description." 93 epic: str | None 94 "Initial epic grouping." 95 name: Required[str] 96 "Initial task name." 97 org: str | None 98 "Explicit organization for privileged callers." 99 source_id: Required[str] 100 "Source identity, for example owner/repo#123." 101 source_scope: Required[str] 102 "Source scope, for example github." 103 source_type: Required[str] 104 "Source type, for example pull_request." 105 status: str | None 106 "Initial task status." 107 team: str | None 108 "Team owner." 109 110 111class UserThreadCreateInputThreadMembersItem(TypedDict): 112 id: str 113 "Public user (`usr_...`) or agent (`agt_...`) ID matching `type`." 114 type: Literal["user", "agent"] 115 "Member kind. Use `user` for a user ID or `agent` for an agent ID." 116 117 118class UserThreadCreateInputThreadProfilePicture(TypedDict, total=False): 119 data: str | None 120 "Base64-encoded image bytes." 121 filename: str | None 122 "Original filename of the uploaded image, used for display and content-type inference." 123 mime_type: str | None 124 'MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`.' 125 126 127class UserThreadCreateInputThreadSettings(TypedDict, total=False): 128 agent_enabled: bool | None 129 "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." 130 131 132class UserThreadCreateInputThread(TypedDict, total=False): 133 create_legacy_agent: bool | None 134 "When `true`, provisions a legacy chat agent alongside the thread. Only needed for integrations that depend on the pre-v2 agent model." 135 description: str | None 136 "Optional longer description of the thread's purpose. `null` if not provided." 137 is_unlisted: bool | None 138 "When `true`, the thread is hidden from the default thread list and accessible only by direct link or ID." 139 key: str | None 140 "Client-assigned unique key for idempotent creation or later lookup. Must be unique within the owning organization." 141 kind: Literal["personal", "feed"] | None 142 "Optional behavioral subtype. `personal` is accepted only for a user-owned thread and limits membership to that user and agents currently owned by them. `feed` is accepted for any owner and renders the thread as a post feed: message lists return top-level posts with their newest replies inline, and agent responses attach to the root post. Mirror kinds remain server-derived and cannot be selected by callers." 143 members: list[UserThreadCreateInputThreadMembersItem] | None 144 "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." 145 metadata: dict[str, Any] | None 146 "Arbitrary key-value pairs stored alongside the thread. Values must be strings or numbers." 147 muted: bool | None 148 "When `true`, push and in-app notifications for this thread are suppressed for the creating user." 149 org_id: str | None 150 "ID of the organization to create the thread under. Defaults to the authenticated user's primary organization when omitted." 151 profile_picture: UserThreadCreateInputThreadProfilePicture | None 152 "Optional profile image for the thread, provided as a base64-encoded payload." 153 settings: UserThreadCreateInputThreadSettings | None 154 "Configuration overrides for the thread, such as AI model selection and context window settings." 155 slug: str | None 156 "Optional URL-safe identifier. Derived from the title when omitted and unique within the thread owner." 157 title: str | None 158 "Display name for the thread. `null` if omitted, which causes the thread to be untitled." 159 visibility: Literal["team", "restricted", "private", "org"] | None 160 "Thread visibility. A team-owned thread with members must explicitly use `restricted` or `private`. User- and agent-owned threads with members default to `private` and reject every other value. `org` is only valid on an organization-owned thread with no team, user, or agent owner." 161 162 163class UserThreadCreateInput(TypedDict, total=False): 164 "Create a thread for a user" 165 166 skip_welcome_message: bool | None 167 "When `true`, suppresses the automatic welcome message that is otherwise sent into the thread on creation. Defaults to `false`." 168 thread: Required[UserThreadCreateInputThread] 169 "Attributes for the new thread. See ThreadCreateParams for the full set of accepted fields." 170 171 172class TokenCreateInput(TypedDict, total=False): 173 "Create a personal access token" 174 175 expires_in_days: int | None 176 "Lifetime in days. One of `7`, `30`, `60`, `90`, or `365`. Defaults to `30`." 177 name: str | None 178 'Human-readable label for the token (e.g. `"Codex MCP"`). Stored as metadata only.' 179 scopes: list[str] | None 180 "Optional OAuth scopes to stamp on the token. Omit for `full_access`." 181 182 183class UserInvitesInputInvite(TypedDict, total=False): 184 metadata: dict[str, Any] | None 185 "Arbitrary key-value metadata to attach to the invite. Returned as-is on the resulting invite object." 186 persona_id: str | None 187 "ID of the persona to associate with this invite (`per_...`). `null` if the invite is not bound to a persona." 188 thread_id: str | None 189 "ID of the thread to associate with this invite (`thr_...`). `null` if the invite is not bound to a thread." 190 191 192class UserInvitesInput(TypedDict): 193 "Create a user invite" 194 195 invite: UserInvitesInputInvite 196 "Parameters for the new invite. See the UserInviteCreateParams schema for field details." 197 198 199class UserProfileInputProfilePicture(TypedDict, total=False): 200 data: str | None 201 "Base64-encoded binary content of the image file." 202 filename: str | None 203 "Original filename of the image, used for storage metadata." 204 mime_type: str | None 205 'MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`.' 206 207 208class UserProfileInput(TypedDict, total=False): 209 "Update the current user's profile" 210 211 alias: str | None 212 "Short display alias shown in place of the full name in compact UI contexts." 213 clear_full_name: bool | None 214 "Set to true to clear the optional display name. Cannot be combined with full_name." 215 clear_profile_picture: bool | None 216 "Set to true to remove the current profile picture. Cannot be combined with profile_picture." 217 full_name: str | None 218 "Updated display name for the user." 219 metadata: dict[str, Any] | None 220 "Arbitrary key-value metadata to associate with the user. Existing keys are merged; pass `null` for a key to remove it." 221 profile_picture: UserProfileInputProfilePicture | None 222 "New profile picture to upload as a base64-encoded image. Replaces any existing picture." 223 224 225class IntegrationAccessTokenResponse(BaseModel): 226 """ 227 Successful response 228 """ 229 230 access_token: str = Field(..., description="GitHub access token. Treat this value as a secret.") 231 expires_at: datetime | None = Field( 232 default=None, description="Access-token expiry, or null for non-expiring tokens." 233 ) 234 integration: str = Field(..., description="Integration ID (`int_...`).") 235 provider: str = Field(..., description="Always `github`.") 236 scopes: list[str] = Field(..., description="Recorded GitHub OAuth scopes.") 237 token_kind: str = Field( 238 ..., description="Credential authority model: `oauth` or `github_app_user`." 239 ) 240 workspace_key: str | None = Field( 241 default=None, description="GitHub login associated with the credential." 242 ) 243 244 245class UserSshKeyListResponseDataItem(BaseModel): 246 algorithm: str = Field(..., description="SSH algorithm. V1 accepts `ssh-ed25519`.") 247 created_at: datetime = Field(..., description="Registration time.") 248 fingerprint: str = Field(..., description="OpenSSH SHA-256 fingerprint.") 249 id: str = Field(..., description="Registered SSH key ID (`ssk_...`).") 250 label: str = Field(..., description="User-visible label for the key.") 251 revoked_at: datetime | None = Field( 252 default=None, description="Revocation time, or null while active." 253 ) 254 255 256class UserSshKeyListResponse(BaseModel): 257 """ 258 Successful response 259 """ 260 261 after_cursor: str | None = None 262 before_cursor: str | None = None 263 data: list[UserSshKeyListResponseDataItem] 264 has_more: bool 265 266 267class UserTaskListResponseDataItemCreatedByActorProfilePicture(BaseModel): 268 file: str | None = Field( 269 default=None, 270 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 271 ) 272 height: int | None = Field( 273 default=None, description="Height of the image in pixels. `null` if not known." 274 ) 275 media: str | None = Field( 276 default=None, 277 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 278 ) 279 mime_type: str | None = Field( 280 default=None, 281 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 282 ) 283 refresh_url: str | None = Field( 284 default=None, 285 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.", 286 ) 287 url: str | None = Field( 288 default=None, 289 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.", 290 ) 291 width: int | None = Field( 292 default=None, description="Width of the image in pixels. `null` if not known." 293 ) 294 295 296class UserTaskListResponseDataItemCreatedByActor(BaseModel): 297 alias: str | None = Field( 298 default=None, 299 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 300 ) 301 id: str | None = Field( 302 default=None, 303 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 304 ) 305 name: str | None = Field( 306 default=None, 307 description="Display name of the actor shown in the UI. `null` if no name is set.", 308 ) 309 profile_picture: UserTaskListResponseDataItemCreatedByActorProfilePicture | None = Field( 310 default=None, 311 description="Profile picture for the actor. `null` if the actor has no profile picture.", 312 ) 313 314 315class UserTaskListResponseDataItemCurrentLease(BaseModel): 316 expires_at: datetime = Field( 317 ..., description="Server-calculated lease expiry in ISO 8601 format." 318 ) 319 harness: str = Field(..., description="Bounded harness identifier for the coding session.") 320 session_name: str = Field( 321 ..., description="Display name supplied by the coding session that holds the lease." 322 ) 323 324 325class UserTaskListResponseDataItemOwnerActorProfilePicture(BaseModel): 326 file: str | None = Field( 327 default=None, 328 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 329 ) 330 height: int | None = Field( 331 default=None, description="Height of the image in pixels. `null` if not known." 332 ) 333 media: str | None = Field( 334 default=None, 335 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 336 ) 337 mime_type: str | None = Field( 338 default=None, 339 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 340 ) 341 refresh_url: str | None = Field( 342 default=None, 343 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.", 344 ) 345 url: str | None = Field( 346 default=None, 347 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.", 348 ) 349 width: int | None = Field( 350 default=None, description="Width of the image in pixels. `null` if not known." 351 ) 352 353 354class UserTaskListResponseDataItemOwnerActor(BaseModel): 355 alias: str | None = Field( 356 default=None, 357 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 358 ) 359 id: str | None = Field( 360 default=None, 361 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 362 ) 363 name: str | None = Field( 364 default=None, 365 description="Display name of the actor shown in the UI. `null` if no name is set.", 366 ) 367 profile_picture: UserTaskListResponseDataItemOwnerActorProfilePicture | None = Field( 368 default=None, 369 description="Profile picture for the actor. `null` if the actor has no profile picture.", 370 ) 371 372 373class UserTaskListResponseDataItem(BaseModel): 374 agent: str | None = Field( 375 default=None, 376 description="ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", 377 ) 378 aggregate_version: int | None = Field( 379 default=None, 380 description="Event-stream version for optimistic update fencing. Pass this value as `expected_version` on an update to reject concurrent writes.", 381 ) 382 blocked_by_count: int | None = Field( 383 default=None, 384 description="Number of readable tasks marked as blocking this task, whether or not they are done (see `GET /tasks/{task}/blockers`). Computed on list/show reads; create/update responses may lag one read behind.", 385 ) 386 closed_at: datetime | None = Field( 387 default=None, 388 description="When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", 389 ) 390 comments_count: int | None = Field( 391 default=None, description="Total number of comments posted on this task." 392 ) 393 created_at: datetime | None = Field( 394 default=None, description="When the task was created (ISO 8601)." 395 ) 396 created_by_actor: UserTaskListResponseDataItemCreatedByActor | None = Field( 397 default=None, 398 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).", 399 ) 400 created_by_agent: str | None = Field( 401 default=None, 402 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.", 403 ) 404 created_by_user: str | None = Field( 405 default=None, 406 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.", 407 ) 408 current_lease: UserTaskListResponseDataItemCurrentLease | None = Field( 409 default=None, 410 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.", 411 ) 412 description: str | None = Field( 413 default=None, 414 description="Long-form description or notes for the task. `null` if no description has been provided.", 415 ) 416 due_date: datetime | None = Field( 417 default=None, 418 description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", 419 ) 420 epic: str | None = Field( 421 default=None, 422 description="Free-form grouping label. `null` when the task is not in an epic.", 423 ) 424 id: str = Field(..., description="Task ID (`tsk_...`).") 425 is_blocked: bool | None = Field( 426 default=None, 427 description="`true` while at least one blocking task is not yet done. Informational only - a blocked task can still change status - and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on reads, including mutation responses.", 428 ) 429 is_stalled: bool | None = Field( 430 default=None, 431 description="True exactly when status is in_progress and the task has no lease or its lease expiry is in the past. Derived at read time from status and lease expiry, including on unannotated reads.", 432 ) 433 links: dict[str, Any] | None = Field( 434 default=None, 435 description="Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.", 436 ) 437 metadata: dict[str, Any] | None = Field( 438 default=None, 439 description="Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.", 440 ) 441 name: str = Field(..., description="Human-readable title of the task.") 442 org: str | None = Field( 443 default=None, 444 description="ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", 445 ) 446 owner_actor: UserTaskListResponseDataItemOwnerActor | None = Field( 447 default=None, 448 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).", 449 ) 450 owner_agent: str | None = Field( 451 default=None, 452 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.", 453 ) 454 owner_user: str | None = Field( 455 default=None, 456 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.", 457 ) 458 parent: str | None = Field( 459 default=None, 460 description="ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks or when the parent is not readable. Subtasks nest exactly one level.", 461 ) 462 priority: int | None = Field( 463 default=None, 464 description="Priority level of the task from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when not explicitly set.", 465 ) 466 project_id: str | None = Field( 467 default=None, 468 description="Optional project ID (`prj_...`). Membership does not change task visibility.", 469 ) 470 sandbox: str | None = Field( 471 default=None, 472 description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", 473 ) 474 source_id: str | None = Field( 475 default=None, 476 description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", 477 ) 478 source_scope: str | None = Field( 479 default=None, 480 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`.", 481 ) 482 source_type: str | None = Field( 483 default=None, 484 description="Kind of source object (for example `repository`). `null` when the task has no source.", 485 ) 486 stalled_since: datetime | None = Field( 487 default=None, 488 description="Lease expiry for a stalled task, or its last update when no lease expiry exists. Null when not stalled.", 489 ) 490 status: str = Field( 491 ..., 492 description='Current status of the task. One of `"open"`, `"in_progress"`, `"in_review"`, `"paused"`, `"failed"`, `"superseding"`, `"done"`, or `"cancelled"`.', 493 ) 494 subtasks_count: int | None = Field( 495 default=None, 496 description="Number of readable subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.", 497 ) 498 tags: list[str] | None = Field( 499 default=None, 500 description="Labels for grouping and filtering, stored lowercase and de-duplicated. Empty array when untagged.", 501 ) 502 target_binary: str | None = Field( 503 default=None, 504 description="Binary that must run this work (for example `my-cli`). A worker should take the task only when its own `target_binary` build is at least `target_version`. `null` when the task has no target. Set together with `target_version`.", 505 ) 506 target_version: str | None = Field( 507 default=None, 508 description="Minimum semantic version of `target_binary` that can run this work (for example `0.48.9`), in canonical `MAJOR.MINOR.PATCH[-prerelease][+build]` form. `null` when the task has no target.", 509 ) 510 team: str | None = Field( 511 default=None, 512 description="ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", 513 ) 514 thread: str | None = Field( 515 default=None, 516 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.", 517 ) 518 updated_at: datetime | None = Field( 519 default=None, description="When the task was last modified (ISO 8601)." 520 ) 521 user: str | None = Field( 522 default=None, 523 description="ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", 524 ) 525 526 527class UserTaskListResponse(BaseModel): 528 """ 529 Successful response 530 """ 531 532 after_cursor: str | None = None 533 before_cursor: str | None = None 534 data: list[UserTaskListResponseDataItem] = Field( 535 ..., description="Array of task objects matching the requested filters." 536 ) 537 has_more: bool 538 539 540class UserTaskBlockerCyclesResponseDataItemTasksItemCreatedByActorProfilePicture(BaseModel): 541 file: str | None = Field( 542 default=None, 543 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 544 ) 545 height: int | None = Field( 546 default=None, description="Height of the image in pixels. `null` if not known." 547 ) 548 media: str | None = Field( 549 default=None, 550 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 551 ) 552 mime_type: str | None = Field( 553 default=None, 554 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 555 ) 556 refresh_url: str | None = Field( 557 default=None, 558 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.", 559 ) 560 url: str | None = Field( 561 default=None, 562 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.", 563 ) 564 width: int | None = Field( 565 default=None, description="Width of the image in pixels. `null` if not known." 566 ) 567 568 569class UserTaskBlockerCyclesResponseDataItemTasksItemCreatedByActor(BaseModel): 570 alias: str | None = Field( 571 default=None, 572 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 573 ) 574 id: str | None = Field( 575 default=None, 576 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 577 ) 578 name: str | None = Field( 579 default=None, 580 description="Display name of the actor shown in the UI. `null` if no name is set.", 581 ) 582 profile_picture: ( 583 UserTaskBlockerCyclesResponseDataItemTasksItemCreatedByActorProfilePicture | None 584 ) = Field( 585 default=None, 586 description="Profile picture for the actor. `null` if the actor has no profile picture.", 587 ) 588 589 590class UserTaskBlockerCyclesResponseDataItemTasksItemCurrentLease(BaseModel): 591 expires_at: datetime = Field( 592 ..., description="Server-calculated lease expiry in ISO 8601 format." 593 ) 594 harness: str = Field(..., description="Bounded harness identifier for the coding session.") 595 session_name: str = Field( 596 ..., description="Display name supplied by the coding session that holds the lease." 597 ) 598 599 600class UserTaskBlockerCyclesResponseDataItemTasksItemOwnerActorProfilePicture(BaseModel): 601 file: str | None = Field( 602 default=None, 603 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 604 ) 605 height: int | None = Field( 606 default=None, description="Height of the image in pixels. `null` if not known." 607 ) 608 media: str | None = Field( 609 default=None, 610 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 611 ) 612 mime_type: str | None = Field( 613 default=None, 614 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 615 ) 616 refresh_url: str | None = Field( 617 default=None, 618 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.", 619 ) 620 url: str | None = Field( 621 default=None, 622 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.", 623 ) 624 width: int | None = Field( 625 default=None, description="Width of the image in pixels. `null` if not known." 626 ) 627 628 629class UserTaskBlockerCyclesResponseDataItemTasksItemOwnerActor(BaseModel): 630 alias: str | None = Field( 631 default=None, 632 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 633 ) 634 id: str | None = Field( 635 default=None, 636 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 637 ) 638 name: str | None = Field( 639 default=None, 640 description="Display name of the actor shown in the UI. `null` if no name is set.", 641 ) 642 profile_picture: ( 643 UserTaskBlockerCyclesResponseDataItemTasksItemOwnerActorProfilePicture | None 644 ) = Field( 645 default=None, 646 description="Profile picture for the actor. `null` if the actor has no profile picture.", 647 ) 648 649 650class UserTaskBlockerCyclesResponseDataItemTasksItem(BaseModel): 651 agent: str | None = Field( 652 default=None, 653 description="ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", 654 ) 655 aggregate_version: int | None = Field( 656 default=None, 657 description="Event-stream version for optimistic update fencing. Pass this value as `expected_version` on an update to reject concurrent writes.", 658 ) 659 blocked_by_count: int | None = Field( 660 default=None, 661 description="Number of readable tasks marked as blocking this task, whether or not they are done (see `GET /tasks/{task}/blockers`). Computed on list/show reads; create/update responses may lag one read behind.", 662 ) 663 closed_at: datetime | None = Field( 664 default=None, 665 description="When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", 666 ) 667 comments_count: int | None = Field( 668 default=None, description="Total number of comments posted on this task." 669 ) 670 created_at: datetime | None = Field( 671 default=None, description="When the task was created (ISO 8601)." 672 ) 673 created_by_actor: UserTaskBlockerCyclesResponseDataItemTasksItemCreatedByActor | None = Field( 674 default=None, 675 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).", 676 ) 677 created_by_agent: str | None = Field( 678 default=None, 679 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.", 680 ) 681 created_by_user: str | None = Field( 682 default=None, 683 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.", 684 ) 685 current_lease: UserTaskBlockerCyclesResponseDataItemTasksItemCurrentLease | None = Field( 686 default=None, 687 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.", 688 ) 689 description: str | None = Field( 690 default=None, 691 description="Long-form description or notes for the task. `null` if no description has been provided.", 692 ) 693 due_date: datetime | None = Field( 694 default=None, 695 description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", 696 ) 697 epic: str | None = Field( 698 default=None, 699 description="Free-form grouping label. `null` when the task is not in an epic.", 700 ) 701 id: str = Field(..., description="Task ID (`tsk_...`).") 702 is_blocked: bool | None = Field( 703 default=None, 704 description="`true` while at least one blocking task is not yet done. Informational only - a blocked task can still change status - and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on reads, including mutation responses.", 705 ) 706 is_stalled: bool | None = Field( 707 default=None, 708 description="True exactly when status is in_progress and the task has no lease or its lease expiry is in the past. Derived at read time from status and lease expiry, including on unannotated reads.", 709 ) 710 links: dict[str, Any] | None = Field( 711 default=None, 712 description="Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.", 713 ) 714 metadata: dict[str, Any] | None = Field( 715 default=None, 716 description="Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.", 717 ) 718 name: str = Field(..., description="Human-readable title of the task.") 719 org: str | None = Field( 720 default=None, 721 description="ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", 722 ) 723 owner_actor: UserTaskBlockerCyclesResponseDataItemTasksItemOwnerActor | None = Field( 724 default=None, 725 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).", 726 ) 727 owner_agent: str | None = Field( 728 default=None, 729 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.", 730 ) 731 owner_user: str | None = Field( 732 default=None, 733 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.", 734 ) 735 parent: str | None = Field( 736 default=None, 737 description="ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks or when the parent is not readable. Subtasks nest exactly one level.", 738 ) 739 priority: int | None = Field( 740 default=None, 741 description="Priority level of the task from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when not explicitly set.", 742 ) 743 project_id: str | None = Field( 744 default=None, 745 description="Optional project ID (`prj_...`). Membership does not change task visibility.", 746 ) 747 sandbox: str | None = Field( 748 default=None, 749 description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", 750 ) 751 source_id: str | None = Field( 752 default=None, 753 description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", 754 ) 755 source_scope: str | None = Field( 756 default=None, 757 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`.", 758 ) 759 source_type: str | None = Field( 760 default=None, 761 description="Kind of source object (for example `repository`). `null` when the task has no source.", 762 ) 763 stalled_since: datetime | None = Field( 764 default=None, 765 description="Lease expiry for a stalled task, or its last update when no lease expiry exists. Null when not stalled.", 766 ) 767 status: str = Field( 768 ..., 769 description='Current status of the task. One of `"open"`, `"in_progress"`, `"in_review"`, `"paused"`, `"failed"`, `"superseding"`, `"done"`, or `"cancelled"`.', 770 ) 771 subtasks_count: int | None = Field( 772 default=None, 773 description="Number of readable subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.", 774 ) 775 tags: list[str] | None = Field( 776 default=None, 777 description="Labels for grouping and filtering, stored lowercase and de-duplicated. Empty array when untagged.", 778 ) 779 target_binary: str | None = Field( 780 default=None, 781 description="Binary that must run this work (for example `my-cli`). A worker should take the task only when its own `target_binary` build is at least `target_version`. `null` when the task has no target. Set together with `target_version`.", 782 ) 783 target_version: str | None = Field( 784 default=None, 785 description="Minimum semantic version of `target_binary` that can run this work (for example `0.48.9`), in canonical `MAJOR.MINOR.PATCH[-prerelease][+build]` form. `null` when the task has no target.", 786 ) 787 team: str | None = Field( 788 default=None, 789 description="ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", 790 ) 791 thread: str | None = Field( 792 default=None, 793 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.", 794 ) 795 updated_at: datetime | None = Field( 796 default=None, description="When the task was last modified (ISO 8601)." 797 ) 798 user: str | None = Field( 799 default=None, 800 description="ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", 801 ) 802 803 804class UserTaskBlockerCyclesResponseDataItem(BaseModel): 805 tasks: list[UserTaskBlockerCyclesResponseDataItemTasksItem] = Field( 806 ..., description="Every unfinished task in this cyclic blocker component." 807 ) 808 809 810class UserTaskBlockerCyclesResponse(BaseModel): 811 """ 812 Successful response 813 """ 814 815 after_cursor: str | None = None 816 before_cursor: str | None = None 817 data: list[UserTaskBlockerCyclesResponseDataItem] 818 has_more: bool 819 820 821class UserTaskReadyResponseDataItemTaskCreatedByActorProfilePicture(BaseModel): 822 file: str | None = Field( 823 default=None, 824 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 825 ) 826 height: int | None = Field( 827 default=None, description="Height of the image in pixels. `null` if not known." 828 ) 829 media: str | None = Field( 830 default=None, 831 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 832 ) 833 mime_type: str | None = Field( 834 default=None, 835 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 836 ) 837 refresh_url: str | None = Field( 838 default=None, 839 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.", 840 ) 841 url: str | None = Field( 842 default=None, 843 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.", 844 ) 845 width: int | None = Field( 846 default=None, description="Width of the image in pixels. `null` if not known." 847 ) 848 849 850class UserTaskReadyResponseDataItemTaskCreatedByActor(BaseModel): 851 alias: str | None = Field( 852 default=None, 853 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 854 ) 855 id: str | None = Field( 856 default=None, 857 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 858 ) 859 name: str | None = Field( 860 default=None, 861 description="Display name of the actor shown in the UI. `null` if no name is set.", 862 ) 863 profile_picture: UserTaskReadyResponseDataItemTaskCreatedByActorProfilePicture | None = Field( 864 default=None, 865 description="Profile picture for the actor. `null` if the actor has no profile picture.", 866 ) 867 868 869class UserTaskReadyResponseDataItemTaskCurrentLease(BaseModel): 870 expires_at: datetime = Field( 871 ..., description="Server-calculated lease expiry in ISO 8601 format." 872 ) 873 harness: str = Field(..., description="Bounded harness identifier for the coding session.") 874 session_name: str = Field( 875 ..., description="Display name supplied by the coding session that holds the lease." 876 ) 877 878 879class UserTaskReadyResponseDataItemTaskOwnerActorProfilePicture(BaseModel): 880 file: str | None = Field( 881 default=None, 882 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 883 ) 884 height: int | None = Field( 885 default=None, description="Height of the image in pixels. `null` if not known." 886 ) 887 media: str | None = Field( 888 default=None, 889 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 890 ) 891 mime_type: str | None = Field( 892 default=None, 893 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 894 ) 895 refresh_url: str | None = Field( 896 default=None, 897 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.", 898 ) 899 url: str | None = Field( 900 default=None, 901 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.", 902 ) 903 width: int | None = Field( 904 default=None, description="Width of the image in pixels. `null` if not known." 905 ) 906 907 908class UserTaskReadyResponseDataItemTaskOwnerActor(BaseModel): 909 alias: str | None = Field( 910 default=None, 911 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 912 ) 913 id: str | None = Field( 914 default=None, 915 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 916 ) 917 name: str | None = Field( 918 default=None, 919 description="Display name of the actor shown in the UI. `null` if no name is set.", 920 ) 921 profile_picture: UserTaskReadyResponseDataItemTaskOwnerActorProfilePicture | None = Field( 922 default=None, 923 description="Profile picture for the actor. `null` if the actor has no profile picture.", 924 ) 925 926 927class UserTaskReadyResponseDataItemTask(BaseModel): 928 agent: str | None = Field( 929 default=None, 930 description="ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", 931 ) 932 aggregate_version: int | None = Field( 933 default=None, 934 description="Event-stream version for optimistic update fencing. Pass this value as `expected_version` on an update to reject concurrent writes.", 935 ) 936 blocked_by_count: int | None = Field( 937 default=None, 938 description="Number of readable tasks marked as blocking this task, whether or not they are done (see `GET /tasks/{task}/blockers`). Computed on list/show reads; create/update responses may lag one read behind.", 939 ) 940 closed_at: datetime | None = Field( 941 default=None, 942 description="When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", 943 ) 944 comments_count: int | None = Field( 945 default=None, description="Total number of comments posted on this task." 946 ) 947 created_at: datetime | None = Field( 948 default=None, description="When the task was created (ISO 8601)." 949 ) 950 created_by_actor: UserTaskReadyResponseDataItemTaskCreatedByActor | None = Field( 951 default=None, 952 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).", 953 ) 954 created_by_agent: str | None = Field( 955 default=None, 956 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.", 957 ) 958 created_by_user: str | None = Field( 959 default=None, 960 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.", 961 ) 962 current_lease: UserTaskReadyResponseDataItemTaskCurrentLease | None = Field( 963 default=None, 964 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.", 965 ) 966 description: str | None = Field( 967 default=None, 968 description="Long-form description or notes for the task. `null` if no description has been provided.", 969 ) 970 due_date: datetime | None = Field( 971 default=None, 972 description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", 973 ) 974 epic: str | None = Field( 975 default=None, 976 description="Free-form grouping label. `null` when the task is not in an epic.", 977 ) 978 id: str = Field(..., description="Task ID (`tsk_...`).") 979 is_blocked: bool | None = Field( 980 default=None, 981 description="`true` while at least one blocking task is not yet done. Informational only - a blocked task can still change status - and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on reads, including mutation responses.", 982 ) 983 is_stalled: bool | None = Field( 984 default=None, 985 description="True exactly when status is in_progress and the task has no lease or its lease expiry is in the past. Derived at read time from status and lease expiry, including on unannotated reads.", 986 ) 987 links: dict[str, Any] | None = Field( 988 default=None, 989 description="Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.", 990 ) 991 metadata: dict[str, Any] | None = Field( 992 default=None, 993 description="Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.", 994 ) 995 name: str = Field(..., description="Human-readable title of the task.") 996 org: str | None = Field( 997 default=None, 998 description="ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", 999 ) 1000 owner_actor: UserTaskReadyResponseDataItemTaskOwnerActor | None = Field( 1001 default=None, 1002 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).", 1003 ) 1004 owner_agent: str | None = Field( 1005 default=None, 1006 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.", 1007 ) 1008 owner_user: str | None = Field( 1009 default=None, 1010 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.", 1011 ) 1012 parent: str | None = Field( 1013 default=None, 1014 description="ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks or when the parent is not readable. Subtasks nest exactly one level.", 1015 ) 1016 priority: int | None = Field( 1017 default=None, 1018 description="Priority level of the task from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when not explicitly set.", 1019 ) 1020 project_id: str | None = Field( 1021 default=None, 1022 description="Optional project ID (`prj_...`). Membership does not change task visibility.", 1023 ) 1024 sandbox: str | None = Field( 1025 default=None, 1026 description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", 1027 ) 1028 source_id: str | None = Field( 1029 default=None, 1030 description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", 1031 ) 1032 source_scope: str | None = Field( 1033 default=None, 1034 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`.", 1035 ) 1036 source_type: str | None = Field( 1037 default=None, 1038 description="Kind of source object (for example `repository`). `null` when the task has no source.", 1039 ) 1040 stalled_since: datetime | None = Field( 1041 default=None, 1042 description="Lease expiry for a stalled task, or its last update when no lease expiry exists. Null when not stalled.", 1043 ) 1044 status: str = Field( 1045 ..., 1046 description='Current status of the task. One of `"open"`, `"in_progress"`, `"in_review"`, `"paused"`, `"failed"`, `"superseding"`, `"done"`, or `"cancelled"`.', 1047 ) 1048 subtasks_count: int | None = Field( 1049 default=None, 1050 description="Number of readable subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.", 1051 ) 1052 tags: list[str] | None = Field( 1053 default=None, 1054 description="Labels for grouping and filtering, stored lowercase and de-duplicated. Empty array when untagged.", 1055 ) 1056 target_binary: str | None = Field( 1057 default=None, 1058 description="Binary that must run this work (for example `my-cli`). A worker should take the task only when its own `target_binary` build is at least `target_version`. `null` when the task has no target. Set together with `target_version`.", 1059 ) 1060 target_version: str | None = Field( 1061 default=None, 1062 description="Minimum semantic version of `target_binary` that can run this work (for example `0.48.9`), in canonical `MAJOR.MINOR.PATCH[-prerelease][+build]` form. `null` when the task has no target.", 1063 ) 1064 team: str | None = Field( 1065 default=None, 1066 description="ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", 1067 ) 1068 thread: str | None = Field( 1069 default=None, 1070 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.", 1071 ) 1072 updated_at: datetime | None = Field( 1073 default=None, description="When the task was last modified (ISO 8601)." 1074 ) 1075 user: str | None = Field( 1076 default=None, 1077 description="ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", 1078 ) 1079 1080 1081class UserTaskReadyResponseDataItem(BaseModel): 1082 readiness: Literal["ready", "blocked", "leased"] = Field( 1083 ..., description="One of `ready`, `blocked`, or `leased`." 1084 ) 1085 reason: Literal["open_blockers", "active_lease"] | None = Field( 1086 default=None, 1087 description="Stable exclusion reason: `open_blockers` or `active_lease`; omitted when ready.", 1088 ) 1089 task: UserTaskReadyResponseDataItemTask = Field( 1090 ..., description="The task evaluated for readiness." 1091 ) 1092 1093 1094class UserTaskReadyResponse(BaseModel): 1095 """ 1096 Successful response 1097 """ 1098 1099 after_cursor: str | None = None 1100 authoritative: bool = Field( 1101 ..., 1102 description="Always false because projections can lag writes and a later claim can race this read.", 1103 ) 1104 before_cursor: str | None = None 1105 data: list[UserTaskReadyResponseDataItem] 1106 has_more: bool 1107 1108 1109class UserTaskSearchResponseDataItemCreatedByActorProfilePicture(BaseModel): 1110 file: str | None = Field( 1111 default=None, 1112 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 1113 ) 1114 height: int | None = Field( 1115 default=None, description="Height of the image in pixels. `null` if not known." 1116 ) 1117 media: str | None = Field( 1118 default=None, 1119 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 1120 ) 1121 mime_type: str | None = Field( 1122 default=None, 1123 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 1124 ) 1125 refresh_url: str | None = Field( 1126 default=None, 1127 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.", 1128 ) 1129 url: str | None = Field( 1130 default=None, 1131 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.", 1132 ) 1133 width: int | None = Field( 1134 default=None, description="Width of the image in pixels. `null` if not known." 1135 ) 1136 1137 1138class UserTaskSearchResponseDataItemCreatedByActor(BaseModel): 1139 alias: str | None = Field( 1140 default=None, 1141 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 1142 ) 1143 id: str | None = Field( 1144 default=None, 1145 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 1146 ) 1147 name: str | None = Field( 1148 default=None, 1149 description="Display name of the actor shown in the UI. `null` if no name is set.", 1150 ) 1151 profile_picture: UserTaskSearchResponseDataItemCreatedByActorProfilePicture | None = Field( 1152 default=None, 1153 description="Profile picture for the actor. `null` if the actor has no profile picture.", 1154 ) 1155 1156 1157class UserTaskSearchResponseDataItemCurrentLease(BaseModel): 1158 expires_at: datetime = Field( 1159 ..., description="Server-calculated lease expiry in ISO 8601 format." 1160 ) 1161 harness: str = Field(..., description="Bounded harness identifier for the coding session.") 1162 session_name: str = Field( 1163 ..., description="Display name supplied by the coding session that holds the lease." 1164 ) 1165 1166 1167class UserTaskSearchResponseDataItemOwnerActorProfilePicture(BaseModel): 1168 file: str | None = Field( 1169 default=None, 1170 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 1171 ) 1172 height: int | None = Field( 1173 default=None, description="Height of the image in pixels. `null` if not known." 1174 ) 1175 media: str | None = Field( 1176 default=None, 1177 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 1178 ) 1179 mime_type: str | None = Field( 1180 default=None, 1181 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 1182 ) 1183 refresh_url: str | None = Field( 1184 default=None, 1185 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.", 1186 ) 1187 url: str | None = Field( 1188 default=None, 1189 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.", 1190 ) 1191 width: int | None = Field( 1192 default=None, description="Width of the image in pixels. `null` if not known." 1193 ) 1194 1195 1196class UserTaskSearchResponseDataItemOwnerActor(BaseModel): 1197 alias: str | None = Field( 1198 default=None, 1199 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 1200 ) 1201 id: str | None = Field( 1202 default=None, 1203 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 1204 ) 1205 name: str | None = Field( 1206 default=None, 1207 description="Display name of the actor shown in the UI. `null` if no name is set.", 1208 ) 1209 profile_picture: UserTaskSearchResponseDataItemOwnerActorProfilePicture | None = Field( 1210 default=None, 1211 description="Profile picture for the actor. `null` if the actor has no profile picture.", 1212 ) 1213 1214 1215class UserTaskSearchResponseDataItem(BaseModel): 1216 agent: str | None = Field( 1217 default=None, 1218 description="ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", 1219 ) 1220 aggregate_version: int | None = Field( 1221 default=None, 1222 description="Event-stream version for optimistic update fencing. Pass this value as `expected_version` on an update to reject concurrent writes.", 1223 ) 1224 blocked_by_count: int | None = Field( 1225 default=None, 1226 description="Number of readable tasks marked as blocking this task, whether or not they are done (see `GET /tasks/{task}/blockers`). Computed on list/show reads; create/update responses may lag one read behind.", 1227 ) 1228 closed_at: datetime | None = Field( 1229 default=None, 1230 description="When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", 1231 ) 1232 comments_count: int | None = Field( 1233 default=None, description="Total number of comments posted on this task." 1234 ) 1235 created_at: datetime | None = Field( 1236 default=None, description="When the task was created (ISO 8601)." 1237 ) 1238 created_by_actor: UserTaskSearchResponseDataItemCreatedByActor | None = Field( 1239 default=None, 1240 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).", 1241 ) 1242 created_by_agent: str | None = Field( 1243 default=None, 1244 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.", 1245 ) 1246 created_by_user: str | None = Field( 1247 default=None, 1248 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.", 1249 ) 1250 current_lease: UserTaskSearchResponseDataItemCurrentLease | None = Field( 1251 default=None, 1252 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.", 1253 ) 1254 description: str | None = Field( 1255 default=None, 1256 description="Long-form description or notes for the task. `null` if no description has been provided.", 1257 ) 1258 due_date: datetime | None = Field( 1259 default=None, 1260 description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", 1261 ) 1262 epic: str | None = Field( 1263 default=None, 1264 description="Free-form grouping label. `null` when the task is not in an epic.", 1265 ) 1266 id: str = Field(..., description="Task ID (`tsk_...`).") 1267 is_blocked: bool | None = Field( 1268 default=None, 1269 description="`true` while at least one blocking task is not yet done. Informational only - a blocked task can still change status - and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on reads, including mutation responses.", 1270 ) 1271 is_stalled: bool | None = Field( 1272 default=None, 1273 description="True exactly when status is in_progress and the task has no lease or its lease expiry is in the past. Derived at read time from status and lease expiry, including on unannotated reads.", 1274 ) 1275 links: dict[str, Any] | None = Field( 1276 default=None, 1277 description="Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.", 1278 ) 1279 metadata: dict[str, Any] | None = Field( 1280 default=None, 1281 description="Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.", 1282 ) 1283 name: str = Field(..., description="Human-readable title of the task.") 1284 org: str | None = Field( 1285 default=None, 1286 description="ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", 1287 ) 1288 owner_actor: UserTaskSearchResponseDataItemOwnerActor | None = Field( 1289 default=None, 1290 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).", 1291 ) 1292 owner_agent: str | None = Field( 1293 default=None, 1294 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.", 1295 ) 1296 owner_user: str | None = Field( 1297 default=None, 1298 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.", 1299 ) 1300 parent: str | None = Field( 1301 default=None, 1302 description="ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks or when the parent is not readable. Subtasks nest exactly one level.", 1303 ) 1304 priority: int | None = Field( 1305 default=None, 1306 description="Priority level of the task from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when not explicitly set.", 1307 ) 1308 project_id: str | None = Field( 1309 default=None, 1310 description="Optional project ID (`prj_...`). Membership does not change task visibility.", 1311 ) 1312 sandbox: str | None = Field( 1313 default=None, 1314 description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", 1315 ) 1316 source_id: str | None = Field( 1317 default=None, 1318 description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", 1319 ) 1320 source_scope: str | None = Field( 1321 default=None, 1322 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`.", 1323 ) 1324 source_type: str | None = Field( 1325 default=None, 1326 description="Kind of source object (for example `repository`). `null` when the task has no source.", 1327 ) 1328 stalled_since: datetime | None = Field( 1329 default=None, 1330 description="Lease expiry for a stalled task, or its last update when no lease expiry exists. Null when not stalled.", 1331 ) 1332 status: str = Field( 1333 ..., 1334 description='Current status of the task. One of `"open"`, `"in_progress"`, `"in_review"`, `"paused"`, `"failed"`, `"superseding"`, `"done"`, or `"cancelled"`.', 1335 ) 1336 subtasks_count: int | None = Field( 1337 default=None, 1338 description="Number of readable subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.", 1339 ) 1340 tags: list[str] | None = Field( 1341 default=None, 1342 description="Labels for grouping and filtering, stored lowercase and de-duplicated. Empty array when untagged.", 1343 ) 1344 target_binary: str | None = Field( 1345 default=None, 1346 description="Binary that must run this work (for example `my-cli`). A worker should take the task only when its own `target_binary` build is at least `target_version`. `null` when the task has no target. Set together with `target_version`.", 1347 ) 1348 target_version: str | None = Field( 1349 default=None, 1350 description="Minimum semantic version of `target_binary` that can run this work (for example `0.48.9`), in canonical `MAJOR.MINOR.PATCH[-prerelease][+build]` form. `null` when the task has no target.", 1351 ) 1352 team: str | None = Field( 1353 default=None, 1354 description="ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", 1355 ) 1356 thread: str | None = Field( 1357 default=None, 1358 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.", 1359 ) 1360 updated_at: datetime | None = Field( 1361 default=None, description="When the task was last modified (ISO 8601)." 1362 ) 1363 user: str | None = Field( 1364 default=None, 1365 description="ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", 1366 ) 1367 1368 1369class UserTaskSearchResponse(BaseModel): 1370 """ 1371 Successful response 1372 """ 1373 1374 after_cursor: str | None = None 1375 before_cursor: str | None = None 1376 data: list[UserTaskSearchResponseDataItem] = Field( 1377 ..., description="Array of task objects matching the query and filters." 1378 ) 1379 has_more: bool 1380 query: str 1381 1382 1383class UserThreadListResponseDataItemParentMessageAclAddItem(BaseModel): 1384 actions: list[str] = Field( 1385 ..., 1386 description='Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.', 1387 ) 1388 principal: str | None = Field( 1389 default=None, 1390 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"`.', 1391 ) 1392 principal_type: str = Field( 1393 ..., 1394 description='The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 1395 ) 1396 1397 1398class UserThreadListResponseDataItemParentMessageAclGrantsItem(BaseModel): 1399 actions: list[str] = Field( 1400 ..., 1401 description='Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.', 1402 ) 1403 principal: str | None = Field( 1404 default=None, 1405 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"`.', 1406 ) 1407 principal_type: str = Field( 1408 ..., 1409 description='The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 1410 ) 1411 1412 1413class UserThreadListResponseDataItemParentMessageAclRemoveItem(BaseModel): 1414 principal: str | None = Field( 1415 default=None, 1416 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"`.', 1417 ) 1418 principal_type: str = Field( 1419 ..., 1420 description='The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 1421 ) 1422 1423 1424class UserThreadListResponseDataItemParentMessageAcl(BaseModel): 1425 add: list[UserThreadListResponseDataItemParentMessageAclAddItem] | None = Field( 1426 default=None, 1427 description="Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", 1428 ) 1429 grants: list[UserThreadListResponseDataItemParentMessageAclGrantsItem] | None = Field( 1430 default=None, 1431 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`.", 1432 ) 1433 remove: list[UserThreadListResponseDataItemParentMessageAclRemoveItem] | None = Field( 1434 default=None, 1435 description="Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`.", 1436 ) 1437 1438 1439class UserThreadListResponseDataItemParentMessageActorsItemProfilePicture(BaseModel): 1440 file: str | None = Field( 1441 default=None, 1442 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 1443 ) 1444 height: int | None = Field( 1445 default=None, description="Height of the image in pixels. `null` if not known." 1446 ) 1447 media: str | None = Field( 1448 default=None, 1449 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 1450 ) 1451 mime_type: str | None = Field( 1452 default=None, 1453 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 1454 ) 1455 refresh_url: str | None = Field( 1456 default=None, 1457 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.", 1458 ) 1459 url: str | None = Field( 1460 default=None, 1461 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.", 1462 ) 1463 width: int | None = Field( 1464 default=None, description="Width of the image in pixels. `null` if not known." 1465 ) 1466 1467 1468class UserThreadListResponseDataItemParentMessageActorsItem(BaseModel): 1469 alias: str | None = Field( 1470 default=None, 1471 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 1472 ) 1473 id: str | None = Field( 1474 default=None, 1475 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 1476 ) 1477 name: str | None = Field( 1478 default=None, 1479 description="Display name of the actor shown in the UI. `null` if no name is set.", 1480 ) 1481 profile_picture: UserThreadListResponseDataItemParentMessageActorsItemProfilePicture | None = ( 1482 Field( 1483 default=None, 1484 description="Profile picture for the actor. `null` if the actor has no profile picture.", 1485 ) 1486 ) 1487 1488 1489class UserThreadListResponseDataItemParentMessageAttachmentsItemImageSource(BaseModel): 1490 file: str | None = Field( 1491 default=None, 1492 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 1493 ) 1494 height: int | None = Field( 1495 default=None, description="Height of the image in pixels. `null` if not known." 1496 ) 1497 media: str | None = Field( 1498 default=None, 1499 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 1500 ) 1501 mime_type: str | None = Field( 1502 default=None, 1503 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 1504 ) 1505 refresh_url: str | None = Field( 1506 default=None, 1507 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.", 1508 ) 1509 url: str | None = Field( 1510 default=None, 1511 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.", 1512 ) 1513 width: int | None = Field( 1514 default=None, description="Width of the image in pixels. `null` if not known." 1515 ) 1516 1517 1518class UserThreadListResponseDataItemParentMessageAttachmentsItemVariantsItemImageSource(BaseModel): 1519 file: str | None = Field( 1520 default=None, 1521 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 1522 ) 1523 height: int | None = Field( 1524 default=None, description="Height of the image in pixels. `null` if not known." 1525 ) 1526 media: str | None = Field( 1527 default=None, 1528 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 1529 ) 1530 mime_type: str | None = Field( 1531 default=None, 1532 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 1533 ) 1534 refresh_url: str | None = Field( 1535 default=None, 1536 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.", 1537 ) 1538 url: str | None = Field( 1539 default=None, 1540 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.", 1541 ) 1542 width: int | None = Field( 1543 default=None, description="Width of the image in pixels. `null` if not known." 1544 ) 1545 1546 1547class UserThreadListResponseDataItemParentMessageAttachmentsItemVariantsItem(BaseModel): 1548 byte_size: int | None = Field(default=None, description="Size of the stored bytes.") 1549 content_type: str | None = Field( 1550 default=None, 1551 description='MIME type of this variant\'s file (e.g., `"image/jpeg"`, `"video/mp4"`). `null` if the file is not loaded.', 1552 ) 1553 created_at: datetime | None = Field( 1554 default=None, description="When this variant was created (ISO 8601)." 1555 ) 1556 duration_ms: int | None = Field( 1557 default=None, 1558 description="Client-declared video duration in milliseconds; not server-probed.", 1559 ) 1560 file: str | None = Field( 1561 default=None, 1562 description="ID of the underlying storage file that backs this variant (`fil_...`).", 1563 ) 1564 filename: str | None = Field( 1565 default=None, 1566 description="Original filename of the uploaded file for this variant. `null` if the file is not loaded.", 1567 ) 1568 height: int | None = Field( 1569 default=None, description="Height of this variant in pixels. `null` if not recorded." 1570 ) 1571 id: str = Field(..., description="Media variant ID (`mvr_...`).") 1572 image_source: ( 1573 UserThreadListResponseDataItemParentMessageAttachmentsItemVariantsItemImageSource | None 1574 ) = Field( 1575 default=None, 1576 description="Resolved image delivery metadata for this variant, including dimensions and CDN URL. `null` for non-image content types.", 1577 ) 1578 sha256: str | None = Field(default=None, description="Lowercase SHA-256 of the stored bytes.") 1579 updated_at: datetime | None = Field( 1580 default=None, description="When this variant was last updated (ISO 8601)." 1581 ) 1582 url: str | None = Field( 1583 default=None, 1584 description="Signed download URL for this variant, resolved at request time. `null` if the file is unavailable.", 1585 ) 1586 url_expires_at: datetime | None = Field( 1587 default=None, description="Expiry of this variant's playable URL." 1588 ) 1589 variant_key: str | None = Field( 1590 default=None, 1591 description='Identifier for this variant\'s processing tier. Common values include `"original"` (the unmodified upload) and `"thumbnail"` (a resized preview).', 1592 ) 1593 width: int | None = Field( 1594 default=None, description="Width of this variant in pixels. `null` if not recorded." 1595 ) 1596 1597 1598class UserThreadListResponseDataItemParentMessageAttachmentsItem(BaseModel): 1599 content_type: str | None = Field( 1600 default=None, 1601 description='MIME type of the attached file, e.g. `"image/png"` or `"application/pdf"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.', 1602 ) 1603 description: str | None = Field( 1604 default=None, 1605 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.", 1606 ) 1607 filename: str | None = Field( 1608 default=None, 1609 description='Original filename of the attached file, e.g. `"report.pdf"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.', 1610 ) 1611 height: int | None = Field( 1612 default=None, 1613 description="Height in pixels of the media item. Present on `media` type only. `null` otherwise.", 1614 ) 1615 id: str = Field(..., description="Unique identifier for this attachment within the message.") 1616 image_height: int | None = Field( 1617 default=None, 1618 description="Height in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", 1619 ) 1620 image_source: UserThreadListResponseDataItemParentMessageAttachmentsItemImageSource | None = ( 1621 Field( 1622 default=None, 1623 description="Image source metadata for inline rendering. Present on `file`, `scraped_link`, `artifact`, and `media` types when the content is an image. `null` otherwise.", 1624 ) 1625 ) 1626 image_url: str | None = Field( 1627 default=None, 1628 description="URL of the preview image extracted from the scraped page. Present on `scraped_link` type only. `null` otherwise.", 1629 ) 1630 image_width: int | None = Field( 1631 default=None, 1632 description="Width in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", 1633 ) 1634 key: str | None = Field( 1635 default=None, 1636 description='For `structured_data` type, what the data is about as set by the sender (for example `"pr:14963"`), copied from the record so it can be read without `object`. Not unique. `null` when unset and on other types.', 1637 ) 1638 media_type: str | None = Field( 1639 default=None, 1640 description='The media category, e.g. `"video"` or `"audio"`. Present on `media` type only; omitted otherwise.', 1641 ) 1642 name: str | None = Field( 1643 default=None, 1644 description="Display name of the media item. Present on `media` type only. `null` otherwise.", 1645 ) 1646 object: dict[str, Any] | None = Field( 1647 default=None, 1648 description="The full embedded object payload. For `task` type, contains the task record. For `action` type, contains the action definition. For `chart` type, contains the chart with its inline `spec`. For `structured_data` type, contains the inline `data` and the `schema_url` or `schema_config` naming its JSON Schema. Omitted on other types.", 1649 ) 1650 title: str | None = Field( 1651 default=None, 1652 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.", 1653 ) 1654 type: str = Field( 1655 ..., 1656 description='The attachment type. One of `"file"`, `"scraped_link"`, `"artifact"`, `"task"`, `"media"`, `"action"`, `"chart"`, or `"structured_data"`. Determines which additional fields are present.', 1657 ) 1658 url: str | None = Field( 1659 default=None, 1660 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.", 1661 ) 1662 variants: ( 1663 list[UserThreadListResponseDataItemParentMessageAttachmentsItemVariantsItem] | None 1664 ) = Field( 1665 default=None, 1666 description="Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only; omitted otherwise.", 1667 ) 1668 version: int | None = Field( 1669 default=None, 1670 description="Version number of the attached artifact at the time of attachment. Present on `artifact` type only. `null` otherwise.", 1671 ) 1672 width: int | None = Field( 1673 default=None, 1674 description="Width in pixels of the media item. Present on `media` type only. `null` otherwise.", 1675 ) 1676 1677 1678class UserThreadListResponseDataItemParentMessageContextItem(BaseModel): 1679 attributes: dict[str, Any] | None = Field( 1680 default=None, 1681 description="Scalar key-value fields describing the context, such as route, repository, or pull-request number.", 1682 ) 1683 content: str | None = Field( 1684 default=None, 1685 description="Optional context body. The model receives it as escaped XML data, not a system instruction.", 1686 ) 1687 title: str | None = Field( 1688 default=None, description="Optional human-readable label for this context block." 1689 ) 1690 type: str = Field( 1691 ..., 1692 description="Stable context kind. Must start with a lowercase letter and contain only lowercase letters, numbers, dots, dashes, or underscores.", 1693 ) 1694 1695 1696class UserThreadListResponseDataItemParentMessageReactionsItem(BaseModel): 1697 payload: dict[str, Any] | None = Field( 1698 default=None, 1699 description='Type-specific reaction data. For `"emoji_reaction"` reactions, contains an `emoji` key with the Unicode emoji string (e.g., `" "`).', 1700 ) 1701 type: str = Field( 1702 ..., 1703 description='Reaction type identifier. Currently always `"emoji_reaction"` for emoji-based reactions.', 1704 ) 1705 user: str | None = Field( 1706 default=None, description="Public ID of the user who added the reaction (`usr_...`)." 1707 ) 1708 1709 1710class UserThreadListResponseDataItemParentMessage(BaseModel): 1711 acl: UserThreadListResponseDataItemParentMessageAcl | None = Field( 1712 default=None, 1713 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.", 1714 ) 1715 actors: list[UserThreadListResponseDataItemParentMessageActorsItem] | None = Field( 1716 default=None, 1717 description="Resolved actor descriptors for the message sender, combining identity and display metadata. Always contains exactly one entry.", 1718 ) 1719 agent: str | None = Field( 1720 default=None, 1721 description="ID of the agent user that sent this message (`agi_...`). `null` for messages sent by human users.", 1722 ) 1723 agent_mode: Literal["cli", "embedded"] | None = Field( 1724 default=None, 1725 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.", 1726 ) 1727 attachments: list[UserThreadListResponseDataItemParentMessageAttachmentsItem] | None = Field( 1728 default=None, 1729 description="Files, links, tasks, media, artifacts, and actions attached to this message. Empty array if there are no attachments.", 1730 ) 1731 branched_thread: str | None = Field( 1732 default=None, 1733 description="ID of the thread that was branched from this message (`thr_...`). `null` if this message has not spawned a branch thread.", 1734 ) 1735 content: str | None = Field( 1736 default=None, 1737 description="Text content of the message. `null` for messages that contain only attachments.", 1738 ) 1739 context: list[UserThreadListResponseDataItemParentMessageContextItem] | None = Field( 1740 default=None, 1741 description="Immutable structured context captured when the message was posted. Each entry has `type`, optional `title` and `content`, and scalar `attributes`. Always present; defaults to an empty array. Context is delivered to agents as escaped XML data, not as system instructions.", 1742 ) 1743 created_at: str | None = Field( 1744 default=None, description="When the message was posted (ISO 8601)." 1745 ) 1746 has_replies: bool | None = Field( 1747 default=None, 1748 description="Whether this message has at least one reply. Only present when explicitly requested or computed by the server.", 1749 ) 1750 id: str = Field(..., description="Message ID (`msg_...`).") 1751 idempotency_key: str | None = Field( 1752 default=None, 1753 description="Client-supplied idempotency key used to deduplicate message sends. `null` if the sender did not provide one.", 1754 ) 1755 is_deleted: bool | None = Field( 1756 default=None, 1757 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.", 1758 ) 1759 legacy_agent: str | None = Field( 1760 default=None, 1761 description="Identifier of the legacy chat agent that sent this message, if applicable. `null` for messages sent by users or modern agent users.", 1762 ) 1763 metadata: dict[str, Any] | None = Field( 1764 default=None, 1765 description="Arbitrary key-value metadata attached to the message. Always present; defaults to an empty object when no metadata has been set.", 1766 ) 1767 org: str | None = Field( 1768 default=None, description="ID of the organization that owns this message (`org_...`)." 1769 ) 1770 reactions: list[UserThreadListResponseDataItemParentMessageReactionsItem] | None = Field( 1771 default=None, 1772 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.", 1773 ) 1774 rendering_mode: str | None = Field( 1775 default=None, 1776 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.', 1777 ) 1778 replies: list[dict[str, Any]] | None = Field( 1779 default=None, 1780 description="Inline array of reply messages, each serialized as a full message object. Only present when the server has preloaded replies for this message.", 1781 ) 1782 replies_after_cursor: str | None = Field( 1783 default=None, 1784 description="Opaque pagination cursor to fetch replies posted after the current page. Only present when inline replies are included in the response.", 1785 ) 1786 replies_before_cursor: str | None = Field( 1787 default=None, 1788 description="Opaque pagination cursor to fetch replies posted before the current page. Only present when inline replies are included in the response.", 1789 ) 1790 reply_count: int | None = Field( 1791 default=None, 1792 description="Total number of direct replies to this message. Only present when explicitly requested or computed by the server.", 1793 ) 1794 reply_to: dict[str, Any] | None = Field( 1795 default=None, 1796 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.", 1797 ) 1798 root_message_id: str | None = Field( 1799 default=None, 1800 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.", 1801 ) 1802 sandbox: str | None = Field( 1803 default=None, 1804 description="ID of the developer sandbox this message belongs to (`dsb_...`). `null` for non-sandbox messages.", 1805 ) 1806 team: str | None = Field( 1807 default=None, 1808 description="ID of the team this message is scoped to (`tem_...`). `null` if the message is not team-scoped.", 1809 ) 1810 thread: str | None = Field( 1811 default=None, description="ID of the thread this message belongs to (`thr_...`)." 1812 ) 1813 type: str | None = Field( 1814 default=None, 1815 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.", 1816 ) 1817 user: str | dict[str, Any] | None = Field( 1818 default=None, 1819 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.", 1820 ) 1821 visibility: Literal["default", "private"] | None = Field( 1822 default=None, 1823 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.", 1824 ) 1825 1826 1827class UserThreadListResponseDataItemParticipantsItem(BaseModel): 1828 alias: str | None = Field( 1829 default=None, description="Short handle or alias for the user. `null` if not set." 1830 ) 1831 app: str | None = Field( 1832 default=None, 1833 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.", 1834 ) 1835 app_name: str | None = Field( 1836 default=None, 1837 description="Display name of the user's app. `null` when the app association was not preloaded by the caller.", 1838 ) 1839 created_by_agent_user: str | None = Field( 1840 default=None, 1841 description="Agent user that created this account (`usr_...`). `null` unless an agent created it.", 1842 ) 1843 created_by_developer: str | None = Field( 1844 default=None, 1845 description="Developer account that created this user (`dva_...`). `null` unless created via a developer token.", 1846 ) 1847 created_by_org: str | None = Field( 1848 default=None, 1849 description="Org of the principal that created this user (`org_...`). `null` on legacy rows.", 1850 ) 1851 created_by_team: str | None = Field( 1852 default=None, 1853 description="Team that created this user (`tem_...`). `null` unless created as a team.", 1854 ) 1855 created_by_user: str | None = Field( 1856 default=None, 1857 description="User who created this account (`usr_...`). `null` on self-signup or legacy rows.", 1858 ) 1859 email: str | None = Field(default=None, description="Email address of the user.") 1860 id: str = Field(..., description="User ID (`usr_...`).") 1861 is_system_user: bool | None = Field( 1862 default=None, 1863 description="`true` if this account is an internal system user rather than a human. System users are created automatically by the platform.", 1864 ) 1865 metadata: dict[str, Any] | None = Field( 1866 default=None, 1867 description="Arbitrary key-value metadata attached to the user. Defaults to an empty object.", 1868 ) 1869 name: str | None = Field( 1870 default=None, 1871 description="Full display name of the user. `null` if the user has not set a name.", 1872 ) 1873 org: str | None = Field( 1874 default=None, 1875 description="ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.", 1876 ) 1877 org_name: str | None = Field( 1878 default=None, 1879 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.", 1880 ) 1881 org_role: str | None = Field( 1882 default=None, 1883 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.', 1884 ) 1885 org_slug: str | None = Field( 1886 default=None, 1887 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.", 1888 ) 1889 sandbox: str | None = Field( 1890 default=None, 1891 description="ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.", 1892 ) 1893 sandbox_name: str | None = Field( 1894 default=None, 1895 description="Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.", 1896 ) 1897 1898 1899class UserThreadListResponseDataItemParticipatingAgentsItemAclAddItem(BaseModel): 1900 actions: list[str] = Field( 1901 ..., 1902 description='Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.', 1903 ) 1904 principal: str | None = Field( 1905 default=None, 1906 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"`.', 1907 ) 1908 principal_type: str = Field( 1909 ..., 1910 description='The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 1911 ) 1912 1913 1914class UserThreadListResponseDataItemParticipatingAgentsItemAclGrantsItem(BaseModel): 1915 actions: list[str] = Field( 1916 ..., 1917 description='Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.', 1918 ) 1919 principal: str | None = Field( 1920 default=None, 1921 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"`.', 1922 ) 1923 principal_type: str = Field( 1924 ..., 1925 description='The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 1926 ) 1927 1928 1929class UserThreadListResponseDataItemParticipatingAgentsItemAclRemoveItem(BaseModel): 1930 principal: str | None = Field( 1931 default=None, 1932 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"`.', 1933 ) 1934 principal_type: str = Field( 1935 ..., 1936 description='The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 1937 ) 1938 1939 1940class UserThreadListResponseDataItemParticipatingAgentsItemAcl(BaseModel): 1941 add: list[UserThreadListResponseDataItemParticipatingAgentsItemAclAddItem] | None = Field( 1942 default=None, 1943 description="Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", 1944 ) 1945 grants: list[UserThreadListResponseDataItemParticipatingAgentsItemAclGrantsItem] | None = Field( 1946 default=None, 1947 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`.", 1948 ) 1949 remove: list[UserThreadListResponseDataItemParticipatingAgentsItemAclRemoveItem] | None = Field( 1950 default=None, 1951 description="Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`.", 1952 ) 1953 1954 1955class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionOrgLogo( 1956 BaseModel 1957): 1958 file: str | None = Field( 1959 default=None, 1960 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 1961 ) 1962 height: int | None = Field( 1963 default=None, description="Height of the image in pixels. `null` if not known." 1964 ) 1965 media: str | None = Field( 1966 default=None, 1967 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 1968 ) 1969 mime_type: str | None = Field( 1970 default=None, 1971 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 1972 ) 1973 refresh_url: str | None = Field( 1974 default=None, 1975 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.", 1976 ) 1977 url: str | None = Field( 1978 default=None, 1979 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.", 1980 ) 1981 width: int | None = Field( 1982 default=None, description="Width of the image in pixels. `null` if not known." 1983 ) 1984 1985 1986class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContractParticipantsItem( 1987 BaseModel 1988): 1989 description: str | None = Field( 1990 default=None, 1991 description="Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", 1992 ) 1993 name: str = Field( 1994 ..., 1995 description="The slot's name, as referenced by the workflow. Supply the chosen agent under the top-level `participants[name]` field when invoking.", 1996 ) 1997 required: bool = Field( 1998 ..., 1999 description="Whether the workflow requires this slot to be filled for the run to complete its embedded stages.", 2000 ) 2001 type: str = Field( 2002 ..., 2003 description='The kind of principal the slot accepts. Currently always `"agent_user"` the value supplied at invoke is an agent ID (`agi_...`).', 2004 ) 2005 2006 2007class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContractPrefills( 2008 BaseModel 2009): 2010 participants: dict[str, Any] | None = Field( 2011 default=None, 2012 description="Participant slot-to-agent mappings applied by the platform. Caller values at these slots must match exactly.", 2013 ) 2014 payload: dict[str, Any] | None = Field( 2015 default=None, 2016 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.", 2017 ) 2018 2019 2020class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContract( 2021 BaseModel 2022): 2023 input_schema: dict[str, Any] | None = Field( 2024 default=None, 2025 description="JSON Schema validated against the whole invoke payload, from the automation's `input_schema_config`. `null` when none is configured.", 2026 ) 2027 participants: ( 2028 list[ 2029 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContractParticipantsItem 2030 ] 2031 | None 2032 ) = Field( 2033 default=None, 2034 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.", 2035 ) 2036 prefills: UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContractPrefills = Field( 2037 ..., 2038 description="Owner-controlled payload and participant values the platform applies to every invocation. Supplying a conflicting value is rejected.", 2039 ) 2040 2041 2042class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetails( 2043 BaseModel 2044): 2045 automation_type: str | None = Field( 2046 default=None, 2047 description="Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", 2048 ) 2049 invoke_contract: ( 2050 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContract 2051 | None 2052 ) = Field( 2053 default=None, 2054 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.", 2055 ) 2056 type: Literal["automation"] = Field( 2057 default="automation", 2058 description="Template-details discriminator. Always `automation` for this variant.", 2059 ) 2060 2061 2062class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItem( 2063 BaseModel 2064): 2065 description: str | None = Field( 2066 default=None, 2067 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.", 2068 ) 2069 details: ( 2070 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetails 2071 | None 2072 ) = Field( 2073 default=None, 2074 description="Template-kind-specific details selected by the `type` discriminator. `null` when this template kind has no additional details.", 2075 ) 2076 display_name: str | None = Field( 2077 default=None, 2078 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`.", 2079 ) 2080 id: str | None = Field( 2081 default=None, 2082 description="Template config ID (`cfg_...`). `null` for inline-only templates.", 2083 ) 2084 kind: str = Field( 2085 ..., 2086 description="Template config kind, or `SolutionTemplateRef` / `SolutionTemplatePath` when unresolved.", 2087 ) 2088 lookup_key: str | None = Field( 2089 default=None, 2090 description="Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", 2091 ) 2092 name: str | None = Field( 2093 default=None, 2094 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`.", 2095 ) 2096 readme_url: str | None = Field( 2097 default=None, 2098 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`.", 2099 ) 2100 virtual_path: str | None = Field( 2101 default=None, 2102 description="Stable virtual path assigned to the template config. `null` when no virtual path was set.", 2103 ) 2104 2105 2106class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolution(BaseModel): 2107 category_keys: list[str] | None = Field( 2108 default=None, 2109 description="Category tag keys declared in the Solution body, used to group Solutions in the catalog. An empty array when the body declares none.", 2110 ) 2111 created_at: str | None = Field( 2112 default=None, description="When the Solution config was first imported (ISO 8601)." 2113 ) 2114 description: str | None = Field( 2115 default=None, 2116 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.", 2117 ) 2118 events: dict[str, Any] | None = Field( 2119 default=None, 2120 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.", 2121 ) 2122 id: str = Field(..., description="Solution config ID (`cfg_...`).") 2123 image_url: str | None = Field( 2124 default=None, 2125 description="Absolute URL of the Solution's cover image the bundled asset the body's `image:` field names. A stable, non-expiring capability URL (like `org_logo.url`), safe to hold in caches and OpenGraph tags; it 404s if the Solution stops declaring a cover. `null` when the Solution has no cover image. Org-only rows remain `null`; when a list entry merges an org copy with its system counterpart, it may reuse the system row's public cover URL. Permanent URLs are never minted for private org assets.", 2126 ) 2127 installed_config_ids: list[str] = Field( 2128 ..., 2129 description="Config IDs (`cfg_...`) of this Solution's installations in the viewer's organization. The array is empty when the Solution is visible only from the system catalog.", 2130 ) 2131 kind: str = Field(..., description='Resource type. Always `"Solution"`.') 2132 latest_solution: str | None = Field( 2133 default=None, 2134 description="When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", 2135 ) 2136 latest_version: str | None = Field( 2137 default=None, 2138 description="When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", 2139 ) 2140 lookup_key: str | None = Field( 2141 default=None, 2142 description="The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", 2143 ) 2144 metadata: dict[str, Any] | None = Field( 2145 default=None, 2146 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.", 2147 ) 2148 name: str | None = Field( 2149 default=None, 2150 description="Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", 2151 ) 2152 org: str | None = Field( 2153 default=None, 2154 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.", 2155 ) 2156 org_logo: ( 2157 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionOrgLogo 2158 | None 2159 ) = Field( 2160 default=None, 2161 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.", 2162 ) 2163 org_name: str | None = Field( 2164 default=None, 2165 description="Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", 2166 ) 2167 org_slug: str | None = Field( 2168 default=None, 2169 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.", 2170 ) 2171 owners: list[str] = Field( 2172 ..., 2173 description='Owner scopes this Solution appears under. Members: `"system"` (app-level system scope) and/or `"org"` (viewer\'s org scope).', 2174 ) 2175 readme_url: str | None = Field( 2176 default=None, 2177 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`.", 2178 ) 2179 screenshot_urls: list[str] | None = Field( 2180 default=None, 2181 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.", 2182 ) 2183 solution_id: str | None = Field( 2184 default=None, 2185 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.", 2186 ) 2187 solution_version: str | None = Field( 2188 default=None, 2189 description='Semver string declared in the Solution body (e.g. `"1.2.0"`). `null` when the body does not declare a version.', 2190 ) 2191 tag_keys: list[str] | None = Field( 2192 default=None, 2193 description="Freeform tag keys declared in the Solution body. An empty array when the body declares none.", 2194 ) 2195 template_kind: str | None = Field( 2196 default=None, 2197 description='Wrapped template kind `"AgentTemplate"`, `"AutomationTemplate"`, `"AgentRoutineTemplate"`, `"AgentToolTemplate"`, `"AgentComputerTemplate"`, or `"SolutionTemplateRef"` for ref-mode bundles.', 2198 ) 2199 templates: list[ 2200 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItem 2201 ] = Field( 2202 ..., 2203 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.", 2204 ) 2205 updated_at: str | None = Field( 2206 default=None, description="When the Solution config was last modified (ISO 8601)." 2207 ) 2208 upgrade_available: bool = Field( 2209 ..., 2210 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.", 2211 ) 2212 virtual_path: str | None = Field( 2213 default=None, 2214 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.", 2215 ) 2216 2217 2218class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionOrgLogo(BaseModel): 2219 file: str | None = Field( 2220 default=None, 2221 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 2222 ) 2223 height: int | None = Field( 2224 default=None, description="Height of the image in pixels. `null` if not known." 2225 ) 2226 media: str | None = Field( 2227 default=None, 2228 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 2229 ) 2230 mime_type: str | None = Field( 2231 default=None, 2232 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 2233 ) 2234 refresh_url: str | None = Field( 2235 default=None, 2236 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.", 2237 ) 2238 url: str | None = Field( 2239 default=None, 2240 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.", 2241 ) 2242 width: int | None = Field( 2243 default=None, description="Width of the image in pixels. `null` if not known." 2244 ) 2245 2246 2247class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContractParticipantsItem( 2248 BaseModel 2249): 2250 description: str | None = Field( 2251 default=None, 2252 description="Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", 2253 ) 2254 name: str = Field( 2255 ..., 2256 description="The slot's name, as referenced by the workflow. Supply the chosen agent under the top-level `participants[name]` field when invoking.", 2257 ) 2258 required: bool = Field( 2259 ..., 2260 description="Whether the workflow requires this slot to be filled for the run to complete its embedded stages.", 2261 ) 2262 type: str = Field( 2263 ..., 2264 description='The kind of principal the slot accepts. Currently always `"agent_user"` the value supplied at invoke is an agent ID (`agi_...`).', 2265 ) 2266 2267 2268class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContractPrefills( 2269 BaseModel 2270): 2271 participants: dict[str, Any] | None = Field( 2272 default=None, 2273 description="Participant slot-to-agent mappings applied by the platform. Caller values at these slots must match exactly.", 2274 ) 2275 payload: dict[str, Any] | None = Field( 2276 default=None, 2277 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.", 2278 ) 2279 2280 2281class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContract( 2282 BaseModel 2283): 2284 input_schema: dict[str, Any] | None = Field( 2285 default=None, 2286 description="JSON Schema validated against the whole invoke payload, from the automation's `input_schema_config`. `null` when none is configured.", 2287 ) 2288 participants: ( 2289 list[ 2290 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContractParticipantsItem 2291 ] 2292 | None 2293 ) = Field( 2294 default=None, 2295 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.", 2296 ) 2297 prefills: UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContractPrefills = Field( 2298 ..., 2299 description="Owner-controlled payload and participant values the platform applies to every invocation. Supplying a conflicting value is rejected.", 2300 ) 2301 2302 2303class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetails( 2304 BaseModel 2305): 2306 automation_type: str | None = Field( 2307 default=None, 2308 description="Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", 2309 ) 2310 invoke_contract: ( 2311 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContract 2312 | None 2313 ) = Field( 2314 default=None, 2315 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.", 2316 ) 2317 type: Literal["automation"] = Field( 2318 default="automation", 2319 description="Template-details discriminator. Always `automation` for this variant.", 2320 ) 2321 2322 2323class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItem( 2324 BaseModel 2325): 2326 description: str | None = Field( 2327 default=None, 2328 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.", 2329 ) 2330 details: ( 2331 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetails 2332 | None 2333 ) = Field( 2334 default=None, 2335 description="Template-kind-specific details selected by the `type` discriminator. `null` when this template kind has no additional details.", 2336 ) 2337 display_name: str | None = Field( 2338 default=None, 2339 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`.", 2340 ) 2341 id: str | None = Field( 2342 default=None, 2343 description="Template config ID (`cfg_...`). `null` for inline-only templates.", 2344 ) 2345 kind: str = Field( 2346 ..., 2347 description="Template config kind, or `SolutionTemplateRef` / `SolutionTemplatePath` when unresolved.", 2348 ) 2349 lookup_key: str | None = Field( 2350 default=None, 2351 description="Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", 2352 ) 2353 name: str | None = Field( 2354 default=None, 2355 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`.", 2356 ) 2357 readme_url: str | None = Field( 2358 default=None, 2359 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`.", 2360 ) 2361 virtual_path: str | None = Field( 2362 default=None, 2363 description="Stable virtual path assigned to the template config. `null` when no virtual path was set.", 2364 ) 2365 2366 2367class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolution(BaseModel): 2368 category_keys: list[str] | None = Field( 2369 default=None, 2370 description="Category tag keys declared in the Solution body, used to group Solutions in the catalog. An empty array when the body declares none.", 2371 ) 2372 created_at: str | None = Field( 2373 default=None, description="When the Solution config was first imported (ISO 8601)." 2374 ) 2375 description: str | None = Field( 2376 default=None, 2377 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.", 2378 ) 2379 events: dict[str, Any] | None = Field( 2380 default=None, 2381 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.", 2382 ) 2383 id: str = Field(..., description="Solution config ID (`cfg_...`).") 2384 image_url: str | None = Field( 2385 default=None, 2386 description="Absolute URL of the Solution's cover image the bundled asset the body's `image:` field names. A stable, non-expiring capability URL (like `org_logo.url`), safe to hold in caches and OpenGraph tags; it 404s if the Solution stops declaring a cover. `null` when the Solution has no cover image. Org-only rows remain `null`; when a list entry merges an org copy with its system counterpart, it may reuse the system row's public cover URL. Permanent URLs are never minted for private org assets.", 2387 ) 2388 installed_config_ids: list[str] = Field( 2389 ..., 2390 description="Config IDs (`cfg_...`) of this Solution's installations in the viewer's organization. The array is empty when the Solution is visible only from the system catalog.", 2391 ) 2392 kind: str = Field(..., description='Resource type. Always `"Solution"`.') 2393 latest_solution: str | None = Field( 2394 default=None, 2395 description="When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", 2396 ) 2397 latest_version: str | None = Field( 2398 default=None, 2399 description="When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", 2400 ) 2401 lookup_key: str | None = Field( 2402 default=None, 2403 description="The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", 2404 ) 2405 metadata: dict[str, Any] | None = Field( 2406 default=None, 2407 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.", 2408 ) 2409 name: str | None = Field( 2410 default=None, 2411 description="Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", 2412 ) 2413 org: str | None = Field( 2414 default=None, 2415 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.", 2416 ) 2417 org_logo: ( 2418 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionOrgLogo | None 2419 ) = Field( 2420 default=None, 2421 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.", 2422 ) 2423 org_name: str | None = Field( 2424 default=None, 2425 description="Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", 2426 ) 2427 org_slug: str | None = Field( 2428 default=None, 2429 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.", 2430 ) 2431 owners: list[str] = Field( 2432 ..., 2433 description='Owner scopes this Solution appears under. Members: `"system"` (app-level system scope) and/or `"org"` (viewer\'s org scope).', 2434 ) 2435 readme_url: str | None = Field( 2436 default=None, 2437 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`.", 2438 ) 2439 screenshot_urls: list[str] | None = Field( 2440 default=None, 2441 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.", 2442 ) 2443 solution_id: str | None = Field( 2444 default=None, 2445 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.", 2446 ) 2447 solution_version: str | None = Field( 2448 default=None, 2449 description='Semver string declared in the Solution body (e.g. `"1.2.0"`). `null` when the body does not declare a version.', 2450 ) 2451 tag_keys: list[str] | None = Field( 2452 default=None, 2453 description="Freeform tag keys declared in the Solution body. An empty array when the body declares none.", 2454 ) 2455 template_kind: str | None = Field( 2456 default=None, 2457 description='Wrapped template kind `"AgentTemplate"`, `"AutomationTemplate"`, `"AgentRoutineTemplate"`, `"AgentToolTemplate"`, `"AgentComputerTemplate"`, or `"SolutionTemplateRef"` for ref-mode bundles.', 2458 ) 2459 templates: list[ 2460 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItem 2461 ] = Field( 2462 ..., 2463 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.", 2464 ) 2465 updated_at: str | None = Field( 2466 default=None, description="When the Solution config was last modified (ISO 8601)." 2467 ) 2468 upgrade_available: bool = Field( 2469 ..., 2470 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.", 2471 ) 2472 virtual_path: str | None = Field( 2473 default=None, 2474 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.", 2475 ) 2476 2477 2478class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionTemplate(BaseModel): 2479 created_at: datetime | None = Field( 2480 default=None, description="When this template config was created (ISO 8601)." 2481 ) 2482 description: str | None = Field( 2483 default=None, 2484 description="Description of the template from the config body. `null` if the current version has no `description` field.", 2485 ) 2486 display_name: str | None = Field( 2487 default=None, 2488 description="Human-readable display name from the config body. `null` if the current version has no `display_name` field.", 2489 ) 2490 id: str = Field(..., description="Template config ID (`cfg_...`).") 2491 kind: str = Field( 2492 ..., description='Config kind identifier for this template (e.g. `"agent_tool_template"`).' 2493 ) 2494 lookup_key: str | None = Field( 2495 default=None, 2496 description="Stable lookup key assigned to this template config. `null` if no lookup key is set.", 2497 ) 2498 name: str | None = Field( 2499 default=None, 2500 description="Template name as stored in the config body. `null` if the current version has no `name` field.", 2501 ) 2502 updated_at: datetime | None = Field( 2503 default=None, description="When this template config was last modified (ISO 8601)." 2504 ) 2505 virtual_path: str | None = Field( 2506 default=None, 2507 description="Virtual filesystem path for this template config. `null` if not set.", 2508 ) 2509 2510 2511class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolution(BaseModel): 2512 current_solution: ( 2513 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolution | None 2514 ) = Field( 2515 default=None, 2516 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.", 2517 ) 2518 solution: UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolution = Field( 2519 ..., 2520 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.", 2521 ) 2522 template: UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionTemplate = Field( 2523 ..., 2524 description="Summary of the AgentTemplate config (`cfg_...`) the agent was last provisioned or updated from.", 2525 ) 2526 2527 2528class UserThreadListResponseDataItemParticipatingAgentsItem(BaseModel): 2529 acl: UserThreadListResponseDataItemParticipatingAgentsItemAcl | None = Field( 2530 default=None, 2531 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.", 2532 ) 2533 app: str | None = Field( 2534 default=None, description="ID of the application that owns this agent (`dap_...`)." 2535 ) 2536 created_at: str | None = Field( 2537 default=None, description="When the agent was created (ISO 8601)." 2538 ) 2539 default_model: str | None = Field( 2540 default=None, 2541 description='Default LLM model identifier used by this agent when no model is specified at runtime (e.g. `"claude-3-7-sonnet-latest"`).', 2542 ) 2543 description: str | None = Field( 2544 default=None, 2545 description="Human-readable description of what the agent does. `null` if not set.", 2546 ) 2547 email: str | None = Field( 2548 default=None, 2549 description="Email address provisioned for this agent. `null` if email delivery is not configured.", 2550 ) 2551 id: str = Field(..., description="Agent ID (`agi_...`).") 2552 identity: str | None = Field( 2553 default=None, 2554 description="System-level identity prompt that shapes the agent's persona and behavior.", 2555 ) 2556 last_applied_template_config: str | None = Field( 2557 default=None, 2558 description="ID of the AgentTemplate config (`cfg_...`) this agent was last provisioned or updated from. `null` for manually created agents.", 2559 ) 2560 lookup_key: str | None = Field( 2561 default=None, 2562 description="Stable, user-defined identifier for this agent within the application. Unique per app.", 2563 ) 2564 metadata: dict[str, Any] | None = Field( 2565 default=None, 2566 description="Arbitrary key-value metadata attached to the agent. Not interpreted by the platform.", 2567 ) 2568 name: str | None = Field( 2569 default=None, description="Human-readable display name for the agent. `null` if not set." 2570 ) 2571 org: str | None = Field( 2572 default=None, 2573 description="ID of the organization this agent belongs to (`org_...`). `null` if the agent is not org-scoped.", 2574 ) 2575 org_name: str | None = Field( 2576 default=None, 2577 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.", 2578 ) 2579 originator: str | None = Field( 2580 default=None, 2581 description="Free-form label identifying the source or author that created this agent (e.g. a username or pipeline name).", 2582 ) 2583 phone_number: str | None = Field( 2584 default=None, 2585 description="Phone number provisioned for this agent. `null` if SMS is not configured.", 2586 ) 2587 sandbox: str | None = Field( 2588 default=None, 2589 description="ID of the sandbox environment this agent is scoped to (`dsb_...`). `null` in production deployments.", 2590 ) 2591 source_solution: UserThreadListResponseDataItemParticipatingAgentsItemSourceSolution | None = ( 2592 Field( 2593 default=None, 2594 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.", 2595 ) 2596 ) 2597 team: str | None = Field( 2598 default=None, 2599 description="ID of the team that owns this agent (`tem_...`). `null` if the agent is not team-scoped.", 2600 ) 2601 template_upgrade_available: bool | None = Field( 2602 default=None, 2603 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`).", 2604 ) 2605 updated_at: str | None = Field( 2606 default=None, description="When the agent was last modified (ISO 8601)." 2607 ) 2608 user: str | None = Field( 2609 default=None, 2610 description="ID of the user that owns this agent (`usr_...`). `null` if the agent is not user-scoped.", 2611 ) 2612 2613 2614class UserThreadListResponseDataItemSettings(BaseModel): 2615 agent_enabled: bool | None = Field( 2616 default=None, 2617 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.", 2618 ) 2619 2620 2621class UserThreadListResponseDataItem(BaseModel): 2622 agent_user: str | None = Field( 2623 default=None, 2624 description="ID of the agent that owns this thread (`agt_...`). `null` for user-owned or team-owned threads.", 2625 ) 2626 created_at: str | None = Field( 2627 default=None, description="When the thread was created (ISO 8601)." 2628 ) 2629 creator: str | dict[str, Any] | None = Field( 2630 default=None, 2631 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.", 2632 ) 2633 description: str | None = Field( 2634 default=None, 2635 description="Optional description or purpose statement for the thread. `null` if not set.", 2636 ) 2637 id: str = Field(..., description="Thread ID (`thr_...`).") 2638 is_channel: bool | None = Field( 2639 default=None, 2640 description="Whether this thread operates as a channel a multi-member broadcast-style conversation.", 2641 ) 2642 is_default: bool | None = Field( 2643 default=None, 2644 description="Whether this is the default thread for its owner. Each user or team has at most one default thread.", 2645 ) 2646 is_transient: bool | None = Field( 2647 default=None, 2648 description="Whether this thread is ephemeral and may be deleted automatically after a period of inactivity or when its TTL expires.", 2649 ) 2650 is_unlisted: bool | None = Field( 2651 default=None, 2652 description="Whether this thread is hidden from public discovery. Unlisted threads are accessible only to direct participants.", 2653 ) 2654 key: str | None = Field( 2655 default=None, 2656 description="Application-defined stable key that uniquely identifies the thread within its scope. Useful for idempotent creation. `null` if not set.", 2657 ) 2658 kind: str | None = Field( 2659 default=None, 2660 description='Thread subtype: `"standard"` for ordinary threads, `"personal"` for a user-and-owned-agents roster, `"feed"` for a post feed with inline replies, `"slack_mirror"` for the membership-strict mirror of a Slack channel, or `"slashwork_mirror"` for the membership-strict mirror of a Slashwork group. `personal` and `feed` are explicit creation options; mirror kinds are server-derived.', 2661 ) 2662 last_activity: str | None = Field( 2663 default=None, 2664 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.", 2665 ) 2666 last_message_preview: str | None = Field( 2667 default=None, 2668 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.", 2669 ) 2670 last_message_sender: str | None = Field( 2671 default=None, 2672 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.", 2673 ) 2674 metadata: dict[str, Any] | None = Field( 2675 default=None, 2676 description="Arbitrary key-value metadata attached to the thread. Shape is application-defined; `null` if no metadata has been set.", 2677 ) 2678 muted: bool | None = Field( 2679 default=None, 2680 description="Whether the authenticated user has muted notifications for this thread. `true` suppresses all notification delivery.", 2681 ) 2682 org: str | None = Field( 2683 default=None, 2684 description="ID of the organization this thread belongs to (`org_...`). `null` for threads outside an org context.", 2685 ) 2686 parent_message: UserThreadListResponseDataItemParentMessage | None = Field( 2687 default=None, 2688 description="The message that spawned this thread as a sub-thread. `null` for top-level threads.", 2689 ) 2690 participant: list[str] | None = Field( 2691 default=None, 2692 description="Array of participant user IDs (`usr_...`) who are members of this thread.", 2693 ) 2694 participants: list[UserThreadListResponseDataItemParticipantsItem] | None = Field( 2695 default=None, 2696 description="Expanded participant user objects for each member of this thread. Populated only when the association is loaded.", 2697 ) 2698 participating_actor: list[str] | None = Field( 2699 default=None, 2700 description="Composite actor identifiers for all participants currently active in this thread. Present only when actor enrichment is requested.", 2701 ) 2702 participating_agents: list[UserThreadListResponseDataItemParticipatingAgentsItem] | None = ( 2703 Field( 2704 default=None, 2705 description="Expanded agent objects for all agents participating in this thread. Present only when agent enrichment is requested.", 2706 ) 2707 ) 2708 role: str | None = Field( 2709 default=None, 2710 description='The authenticated user\'s membership role in this thread, e.g. `"owner"`, `"member"`, or `"viewer"`. `null` if the user is not a member.', 2711 ) 2712 sandbox: str | None = Field( 2713 default=None, 2714 description="ID of the developer sandbox this thread is scoped to (`dsb_...`). `null` for production threads.", 2715 ) 2716 settings: UserThreadListResponseDataItemSettings | None = Field( 2717 default=None, 2718 description="Per-thread configuration settings controlling AI agent behavior for this thread.", 2719 ) 2720 slug: str | None = Field( 2721 default=None, 2722 description="URL-safe slug for the thread, used in human-readable permalinks. `null` if not assigned.", 2723 ) 2724 sub_threads: list[dict[str, Any]] | None = Field( 2725 default=None, 2726 description="Threads that are nested under this thread as replies to a parent message. Present only when sub-thread enrichment is requested.", 2727 ) 2728 tags: list[str] | None = Field( 2729 default=None, 2730 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.', 2731 ) 2732 team: str | None = Field( 2733 default=None, 2734 description="ID of the team that owns this thread (`team_...`). `null` for user-owned or agent-owned threads.", 2735 ) 2736 title: str | None = Field( 2737 default=None, 2738 description="Human-readable name of the thread. `null` if no title has been set.", 2739 ) 2740 ttl: str | None = Field( 2741 default=None, 2742 description="Offset-free expiry timestamp after which the thread may be automatically cleaned up. `null` if the thread does not expire.", 2743 ) 2744 unread_count: int | None = Field( 2745 default=None, 2746 description="Number of messages in this thread that the authenticated user has not yet read. Present only when read-state enrichment is requested.", 2747 ) 2748 updated_at: str | None = Field( 2749 default=None, description="When the thread was last modified (ISO 8601)." 2750 ) 2751 user: str | None = Field( 2752 default=None, 2753 description="ID of the user who owns this thread (`usr_...`). `null` for team-owned or agent-owned threads.", 2754 ) 2755 visibility: Literal["team", "restricted", "private", "org"] = Field( 2756 ..., 2757 description="Who can read the thread: `team` for every owning-team member, `restricted` for team-readable threads with an explicit roster, `private` for roster-only access, or `org` for every member of the owning organization.", 2758 ) 2759 2760 2761class UserThreadListResponse(BaseModel): 2762 """ 2763 Successful response 2764 """ 2765 2766 data: list[UserThreadListResponseDataItem] = Field( 2767 ..., 2768 description="Array of thread objects matching the requested filters and agent narrowings.", 2769 ) 2770 2771 2772class TokenListResponseDataItem(BaseModel): 2773 created_at: datetime | None = Field( 2774 default=None, description="When this token was created (ISO 8601)." 2775 ) 2776 created_by_agent_user: str | None = Field( 2777 default=None, 2778 description="Agent user that minted this token (`usr_...`). `null` unless an agent minted it.", 2779 ) 2780 created_by_developer: str | None = Field( 2781 default=None, 2782 description="Developer account that minted this token (`dva_...`). `null` unless minted with a developer token.", 2783 ) 2784 created_by_org: str | None = Field( 2785 default=None, 2786 description="Org of the principal that minted this token (`org_...`). `null` on legacy rows.", 2787 ) 2788 created_by_team: str | None = Field( 2789 default=None, 2790 description="Team that minted this token (`tem_...`). `null` unless minted as a team.", 2791 ) 2792 created_by_user: str | None = Field( 2793 default=None, 2794 description="User who minted this token (`usr_...`). Distinct from the token subject. `null` on legacy rows.", 2795 ) 2796 expires_at: datetime | None = Field( 2797 default=None, 2798 description="When the token expires. `null` on legacy rows that predate stored expiry.", 2799 ) 2800 id: str = Field(..., description="Token ID (`sat_...`).") 2801 last_used_at: datetime | None = Field( 2802 default=None, 2803 description="When this token was last used to authenticate a request. `null` if the token has never been used.", 2804 ) 2805 name: str | None = Field( 2806 default=None, 2807 description="Human-readable label assigned to this token at creation time. `null` when no label was supplied.", 2808 ) 2809 revoked_at: datetime | None = Field( 2810 default=None, 2811 description="When this token was revoked. `null` if the token is still active.", 2812 ) 2813 scopes: str | None = Field( 2814 default=None, 2815 description="Space-separated OAuth scopes stamped on the token. `null` on legacy rows; treat as `full_access`.", 2816 ) 2817 token: str | None = Field( 2818 default=None, 2819 description="Raw bearer token string. Present only in the response to the create request; never returned again after that.", 2820 ) 2821 2822 2823class TokenListResponse(BaseModel): 2824 """ 2825 Successful response 2826 """ 2827 2828 data: list[TokenListResponseDataItem] = Field( 2829 ..., description="Array of access token objects. Raw JWT values are not included." 2830 ) 2831 2832 2833class UserArtifactsResponseDataItemAclAddItem(BaseModel): 2834 actions: list[str] = Field( 2835 ..., 2836 description='Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.', 2837 ) 2838 principal: str | None = Field( 2839 default=None, 2840 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"`.', 2841 ) 2842 principal_type: str = Field( 2843 ..., 2844 description='The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 2845 ) 2846 2847 2848class UserArtifactsResponseDataItemAclGrantsItem(BaseModel): 2849 actions: list[str] = Field( 2850 ..., 2851 description='Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.', 2852 ) 2853 principal: str | None = Field( 2854 default=None, 2855 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"`.', 2856 ) 2857 principal_type: str = Field( 2858 ..., 2859 description='The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 2860 ) 2861 2862 2863class UserArtifactsResponseDataItemAclRemoveItem(BaseModel): 2864 principal: str | None = Field( 2865 default=None, 2866 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"`.', 2867 ) 2868 principal_type: str = Field( 2869 ..., 2870 description='The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 2871 ) 2872 2873 2874class UserArtifactsResponseDataItemAcl(BaseModel): 2875 add: list[UserArtifactsResponseDataItemAclAddItem] | None = Field( 2876 default=None, 2877 description="Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", 2878 ) 2879 grants: list[UserArtifactsResponseDataItemAclGrantsItem] | None = Field( 2880 default=None, 2881 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`.", 2882 ) 2883 remove: list[UserArtifactsResponseDataItemAclRemoveItem] | None = Field( 2884 default=None, 2885 description="Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`.", 2886 ) 2887 2888 2889class UserArtifactsResponseDataItemImageSource(BaseModel): 2890 file: str | None = Field( 2891 default=None, 2892 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 2893 ) 2894 height: int | None = Field( 2895 default=None, description="Height of the image in pixels. `null` if not known." 2896 ) 2897 media: str | None = Field( 2898 default=None, 2899 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 2900 ) 2901 mime_type: str | None = Field( 2902 default=None, 2903 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 2904 ) 2905 refresh_url: str | None = Field( 2906 default=None, 2907 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.", 2908 ) 2909 url: str | None = Field( 2910 default=None, 2911 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.", 2912 ) 2913 width: int | None = Field( 2914 default=None, description="Width of the image in pixels. `null` if not known." 2915 ) 2916 2917 2918class UserArtifactsResponseDataItem(BaseModel): 2919 acl: UserArtifactsResponseDataItemAcl | None = Field( 2920 default=None, 2921 description="Access control list for the artifact. Contains a `grants` array where each entry specifies `principal_type`, `principal`, and `actions` (`read`, `write`). `null` when the artifact has no grants or the viewer is not its owner.", 2922 ) 2923 agent: str | None = Field( 2924 default=None, 2925 description="ID of the agent that produced this artifact (`agt_...`). `null` if not agent-produced.", 2926 ) 2927 content_type: str | None = Field( 2928 default=None, 2929 description='MIME type of the current version\'s file, e.g. `"text/csv"` or `"image/png"`. `null` if no file is attached.', 2930 ) 2931 created_at: datetime | None = Field( 2932 default=None, description="When the artifact was first created (ISO 8601)." 2933 ) 2934 current_version: str | None = Field( 2935 default=None, 2936 description="ID of the current (latest published) artifact version (`artv_...`). `null` if no version has been published.", 2937 ) 2938 description: str | None = Field( 2939 default=None, 2940 description="Optional longer description of the artifact's contents or purpose. `null` if not set.", 2941 ) 2942 file: str | None = Field( 2943 default=None, 2944 description="Storage file ID for the current version (`fil_...`). `null` if no file is attached.", 2945 ) 2946 file_name: str | None = Field( 2947 default=None, 2948 description='Original filename of the current version\'s file, e.g. `"output.csv"`. `null` if no file is attached.', 2949 ) 2950 file_url: str | None = Field( 2951 default=None, 2952 description="Short-lived signed URL for downloading the current version's file. `null` if no file is attached.", 2953 ) 2954 group_key: str | None = Field( 2955 default=None, 2956 description="Optional nonunique, case-sensitive grouping key, limited to 1024 UTF-8 bytes. Null when unset; belongs to the artifact, not a content version.", 2957 ) 2958 id: str = Field(..., description="Artifact ID (`art_...`).") 2959 image_source: UserArtifactsResponseDataItemImageSource | None = Field( 2960 default=None, 2961 description='Image source metadata for rendering the current version\'s file inline. Present only when `content_type` starts with `"image/"`. `null` otherwise.', 2962 ) 2963 name: str | None = Field( 2964 default=None, 2965 description='Human-readable name for the artifact, e.g. `"Q2 Report"`. `null` if not set.', 2966 ) 2967 org: str | None = Field( 2968 default=None, description="ID of the organization this artifact belongs to (`org_...`)." 2969 ) 2970 sandbox: str | None = Field( 2971 default=None, 2972 description="Identifier of the sandbox environment associated with this artifact. `null` if not sandbox-scoped.", 2973 ) 2974 system: bool | None = Field( 2975 default=None, 2976 description="True when the artifact has no user, team, or agent owner. An organization may own a system artifact.", 2977 ) 2978 team: str | None = Field( 2979 default=None, 2980 description="ID of the team that owns this artifact (`tea_...`). `null` if not team-scoped.", 2981 ) 2982 thread: str | None = Field( 2983 default=None, 2984 description="ID of the thread in which this artifact was created (`thr_...`). `null` if not thread-scoped.", 2985 ) 2986 updated_at: datetime | None = Field( 2987 default=None, description="When the artifact record was last modified (ISO 8601)." 2988 ) 2989 user: str | None = Field( 2990 default=None, 2991 description="ID of the user who created this artifact (`usr_...`). `null` if not user-scoped.", 2992 ) 2993 version: int | None = Field( 2994 default=None, 2995 description="Current version number of the artifact. Increments each time a new version is published.", 2996 ) 2997 2998 2999class UserArtifactsResponse(BaseModel): 3000 """ 3001 Successful response 3002 """ 3003 3004 data: list[UserArtifactsResponseDataItem] = Field( 3005 ..., description="Array of artifact objects belonging to the user." 3006 ) 3007 3008 3009class UserOrgsResponseDataItem(BaseModel): 3010 created_at: datetime | None = Field( 3011 default=None, description="When this organization was created (ISO 8601)." 3012 ) 3013 description: str | None = Field( 3014 default=None, 3015 description="Short human-readable description of the organization. `null` if not set.", 3016 ) 3017 domain: str | None = Field( 3018 default=None, 3019 description='Primary domain associated with the organization, e.g. `"acme.com"`. `null` if not configured.', 3020 ) 3021 id: str = Field(..., description="Organization ID (`org_...`).") 3022 industry: str | None = Field( 3023 default=None, 3024 description='Industry category the organization belongs to, e.g. `"fintech"` or `"healthcare"`. `null` if not set.', 3025 ) 3026 kind: Literal["company", "personal"] = Field( 3027 ..., description="Whether this is a company-domain org or a person-owned personal org." 3028 ) 3029 name: str | None = Field( 3030 default=None, 3031 description="Display name of the organization. `null` if the org has not set a name.", 3032 ) 3033 onboarding_solution_lookup_key: str | None = Field( 3034 default=None, 3035 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.", 3036 ) 3037 onboarding_track: str | None = Field( 3038 default=None, 3039 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.', 3040 ) 3041 owned_products: list[str] | None = Field( 3042 default=None, 3043 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.', 3044 ) 3045 owner_user: str | None = Field( 3046 default=None, description="Owner user ID for a personal org. `null` for company orgs." 3047 ) 3048 sandbox: str | None = Field( 3049 default=None, 3050 description="ID of the sandbox environment scoped to this organization (`snd_...`). `null` for organizations in production mode.", 3051 ) 3052 slug: str | None = Field( 3053 default=None, 3054 description="URL-safe identifier for the organization, used in vanity URLs and slug-based lookups.", 3055 ) 3056 status: str | None = Field( 3057 default=None, 3058 description='Current lifecycle status of the organization, e.g. `"active"` or `"suspended"`. `null` if the status has not been set.', 3059 ) 3060 updated_at: datetime | None = Field( 3061 default=None, description="When this organization was last modified (ISO 8601)." 3062 ) 3063 website: str | None = Field( 3064 default=None, description="Public website URL for the organization. `null` if not set." 3065 ) 3066 3067 3068class UserOrgsResponse(BaseModel): 3069 """ 3070 Successful response 3071 """ 3072 3073 data: list[UserOrgsResponseDataItem] = Field( 3074 ..., 3075 description="Array of organization objects the user belongs to. Contains at most one item.", 3076 ) 3077 3078 3079class UserTaskEpicsResponseDataItemNextReadyItem(BaseModel): 3080 id: str 3081 name: str 3082 priority: int 3083 status: str 3084 3085 3086class UserTaskEpicsResponseDataItemRootBlockersItem(BaseModel): 3087 downstream_count: int 3088 id: str 3089 name: str 3090 priority: int 3091 status: str 3092 3093 3094class UserTaskEpicsResponseDataItem(BaseModel): 3095 blocked_count: int 3096 counts: dict[str, Any] = Field( 3097 ..., description="Task counts keyed by status, including closed tasks." 3098 ) 3099 epic: str 3100 next_ready: list[UserTaskEpicsResponseDataItemNextReadyItem] 3101 root_blockers: list[UserTaskEpicsResponseDataItemRootBlockersItem] 3102 root_blockers_partial: bool = Field( 3103 ..., description="True when root ranking used a truncated in-epic graph." 3104 ) 3105 top_open_priority: int | None = None 3106 updated_at: datetime 3107 3108 3109class UserTaskEpicsResponse(BaseModel): 3110 """ 3111 Successful response 3112 """ 3113 3114 after_cursor: str | None = None 3115 before_cursor: str | None = None 3116 data: list[UserTaskEpicsResponseDataItem] 3117 has_more: bool 3118 no_epic_open_count: int 3119 3120 3121class AsyncIntegrationResource: 3122 def __init__(self, http: HttpClient): 3123 self._http = http 3124 3125 async def access_token(self, user: str, provider: str) -> IntegrationAccessTokenResponse: 3126 """ 3127 Retrieve a GitHub integration access token 3128 Returns a valid GitHub access token for one integration owned by the 3129 authenticated user. Expired tokens are refreshed before the response is 3130 returned. 3131 This endpoint accepts the user's own bearer token, or the app's secret key 3132 acting server-to-server for one of its users. Developer, agent, team, and 3133 cross-user viewers cannot retrieve the credential. Responses are marked 3134 `Cache-Control: no-store`. 3135 3136 Args: 3137 user: User ID (`usr_...`). The authenticated user, or a user of the app whose secret key is presented. 3138 provider: Integration provider. Only `github` is accepted. 3139 3140 Returns: 3141 Successful response 3142 """ 3143 return await self._http.request( 3144 f"/api/v1/users/{user}/integrations/{provider}/access_token", 3145 response_type=IntegrationAccessTokenResponse, 3146 ) 3147 3148 3149class AsyncUserSshKeyResource: 3150 def __init__(self, http: HttpClient): 3151 self._http = http 3152 3153 async def list( 3154 self, user: str, *, limit: int | None = None, after_cursor: str | None = None 3155 ) -> UserSshKeyListResponse: 3156 """ 3157 List registered SSH keys 3158 Returns a cursor-paginated page of SSH-key metadata for the authenticated user. 3159 3160 Args: 3161 user: User ID (`usr_...`) or `me`. 3162 limit: Maximum keys per page. Defaults to 50; maximum is 100. 3163 after_cursor: Opaque cursor for the next page of older keys. 3164 3165 Returns: 3166 Successful response 3167 """ 3168 query: dict[str, object] = {} 3169 if limit is not None: 3170 query["limit"] = limit 3171 if after_cursor is not None: 3172 query["after_cursor"] = after_cursor 3173 return await self._http.request( 3174 f"/api/v1/users/{user}/ssh_keys", 3175 query=query, 3176 response_type=UserSshKeyListResponse, 3177 ) 3178 3179 async def create(self, user: str, input: UserSshKeyCreateInput) -> UserSSHKey: 3180 """ 3181 Register an SSH public key 3182 Registers one comment-free Ed25519 public key for Git-over-SSH. The key is 3183 encrypted before storage; responses expose only its label, algorithm and 3184 OpenSSH SHA-256 fingerprint. 3185 The caller must be the user named by `user` and must present a first-party 3186 session or a `full_access` personal access token. 3187 3188 Args: 3189 user: User ID (`usr_...`) or `me`. 3190 input: Request body. 3191 input.label: A label such as `Work laptop`. 3192 input.public_key: One `ssh-ed25519 <base64>` public key without options or a comment. 3193 3194 Returns: 3195 Metadata for the registered key; no key material. 3196 """ 3197 return await self._http.request( 3198 f"/api/v1/users/{user}/ssh_keys", 3199 method="POST", 3200 body=input, 3201 response_type=UserSSHKey, 3202 ) 3203 3204 3205class AsyncUserTaskResource: 3206 def __init__(self, http: HttpClient): 3207 self._http = http 3208 3209 async def list( 3210 self, 3211 user: str, 3212 *, 3213 team: str | None = None, 3214 org: str | None = None, 3215 status: str | None = None, 3216 owner_user: str | None = None, 3217 owner_agent: str | None = None, 3218 priority: int | None = None, 3219 tag: str | None = None, 3220 parent: str | None = None, 3221 source_scope: str | None = None, 3222 source_type: str | None = None, 3223 source_id: str | None = None, 3224 epic: str | None = None, 3225 search: str | None = None, 3226 sort: str | None = None, 3227 order: str | None = None, 3228 due_before: str | None = None, 3229 due_after: str | None = None, 3230 overdue: bool | None = None, 3231 ready: bool | None = None, 3232 attention: bool | None = None, 3233 limit: int | None = None, 3234 after_cursor: str | None = None, 3235 ) -> UserTaskListResponse: 3236 """ 3237 List an owner's tasks 3238 Returns tasks owned by the specified user or team. You can narrow results using the 3239 optional filters below. By default results are returned in reverse chronological 3240 order (most recently created first); use `sort` and `order` to sort by due date or 3241 priority instead. 3242 User-authenticated callers may list their personal tasks or tasks for teams they 3243 have joined. Privileged callers provide the owner in the route; the owner's 3244 organization is implied by that principal. An explicit `org` is optional and, 3245 when set, must match the owner's organization. 3246 3247 Args: 3248 user: User ID (`usr_...`) for user-scoped tasks. 3249 team: Team ID (`tem_...`). Only tasks belonging to this team are returned. 3250 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. 3251 status: Filter tasks by status. One of `"open"`, `"in_progress"`, `"in_review"`, or `"done"`. Omit to return tasks in all statuses. 3252 owner_user: Filter tasks assigned to a specific user. Provide the user's public ID (`usr_...`). 3253 owner_agent: Filter tasks assigned to a specific agent. Provide the agent's public ID (`agi_...`). 3254 priority: Filter tasks by priority, from 0 (highest) to 4 (lowest). 3255 tag: Return only tasks carrying this tag (matched against the canonical lowercase form). 3256 parent: Return only subtasks of the given task (`tsk_...`), or pass `none` to return only top-level tasks. 3257 source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 3258 source_type: Return only tasks whose source matches this object kind. Must be supplied with the other source filters. 3259 source_id: Return only tasks whose source matches this object identity. Must be supplied with the other source filters. 3260 epic: Return only tasks with this exact epic label. 3261 search: Restrict results to tasks whose name or description contains this string. 3262 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. 3263 order: Sort direction, `"asc"` or `"desc"`. Defaults to `"desc"` for `created` and `"asc"` for `due_date` and `priority`. 3264 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. 3265 due_after: Return only tasks with a due date strictly after this ISO 8601 datetime or date. Tasks without a due date are excluded. 3266 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. 3267 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. 3268 attention: When true, return paused, failed, or in-progress tasks with no lease or a past lease expiry. 3269 limit: Maximum number of tasks to return. Capped at 100. 3270 after_cursor: Opaque cursor returned by the previous page. 3271 3272 Returns: 3273 Successful response 3274 """ 3275 query: dict[str, object] = {} 3276 if team is not None: 3277 query["team"] = team 3278 if org is not None: 3279 query["org"] = org 3280 if status is not None: 3281 query["status"] = status 3282 if owner_user is not None: 3283 query["owner_user"] = owner_user 3284 if owner_agent is not None: 3285 query["owner_agent"] = owner_agent 3286 if priority is not None: 3287 query["priority"] = priority 3288 if tag is not None: 3289 query["tag"] = tag 3290 if parent is not None: 3291 query["parent"] = parent 3292 if source_scope is not None: 3293 query["source_scope"] = source_scope 3294 if source_type is not None: 3295 query["source_type"] = source_type 3296 if source_id is not None: 3297 query["source_id"] = source_id 3298 if epic is not None: 3299 query["epic"] = epic 3300 if search is not None: 3301 query["search"] = search 3302 if sort is not None: 3303 query["sort"] = sort 3304 if order is not None: 3305 query["order"] = order 3306 if due_before is not None: 3307 query["due_before"] = due_before 3308 if due_after is not None: 3309 query["due_after"] = due_after 3310 if overdue is not None: 3311 query["overdue"] = overdue 3312 if ready is not None: 3313 query["ready"] = ready 3314 if attention is not None: 3315 query["attention"] = attention 3316 if limit is not None: 3317 query["limit"] = limit 3318 if after_cursor is not None: 3319 query["after_cursor"] = after_cursor 3320 return await self._http.request( 3321 f"/api/v1/users/{user}/tasks", 3322 query=query, 3323 response_type=UserTaskListResponse, 3324 ) 3325 3326 async def create(self, user: str, input: UserTaskCreateInput) -> Task: 3327 """ 3328 Create a task for an owner 3329 Creates a new task owned by the specified user or team and returns the full 3330 task object. User-authenticated calls are attributed to the authenticated 3331 user or agent. App-scoped developer and server-to-server callers must provide 3332 the task's explicit `org` scope and an explicit `user` or `agent` actor for 3333 team tasks; a user-owned task reuses the user in the route unless an explicit 3334 agent is supplied. Every referenced principal is validated against the app, 3335 owner, and team membership before creation. 3336 3337 Args: 3338 user: User ID (`usr_...`) for user-scoped tasks. 3339 input: Request body. 3340 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. 3341 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. 3342 input.task: Attributes for the task to create. `name` is required; all other fields are optional. 3343 input.team: Team ID (`tem_...`). The task will be owned by this team. 3344 3345 Returns: 3346 The newly created task. 3347 """ 3348 return await self._http.request( 3349 f"/api/v1/users/{user}/tasks", 3350 method="POST", 3351 body=input, 3352 response_type=Task, 3353 ) 3354 3355 async def blocker_cycles( 3356 self, 3357 user: str, 3358 *, 3359 team: str | None = None, 3360 org: str | None = None, 3361 limit: int | None = None, 3362 after_cursor: str | None = None, 3363 ) -> UserTaskBlockerCyclesResponse: 3364 """ 3365 List task blocker cycles 3366 Runs an on-demand diagnostic over unfinished tasks owned by the specified 3367 team or user and returns a forward cursor-paginated page of complete cyclic 3368 blocker components. Detection is bounded to owners with at most 100 3369 unfinished tasks. This endpoint is read-only: cycles do not prevent task 3370 updates, lease acquisition, or completion. 3371 3372 Args: 3373 user: User ID (`usr_...`) for user-scoped tasks. 3374 team: Team ID (`tem_...`) owning the tasks. 3375 org: Optional organization context for privileged callers. 3376 limit: Maximum cycle components to return. Defaults to 50; maximum is 100. 3377 after_cursor: Opaque cursor returned by the preceding page. 3378 3379 Returns: 3380 Successful response 3381 """ 3382 query: dict[str, object] = {} 3383 if team is not None: 3384 query["team"] = team 3385 if org is not None: 3386 query["org"] = org 3387 if limit is not None: 3388 query["limit"] = limit 3389 if after_cursor is not None: 3390 query["after_cursor"] = after_cursor 3391 return await self._http.request( 3392 f"/api/v1/users/{user}/tasks/blocker_cycles", 3393 query=query, 3394 response_type=UserTaskBlockerCyclesResponse, 3395 ) 3396 3397 async def by_source(self, user: str, input: UserTaskBySourceInput) -> TaskEnsureResult: 3398 """ 3399 Find or create a task by source 3400 Atomically creates one task per owner, tenant and source. Retries return the current task without updating it. Historical tasks created through ordinary create are not adopted. 3401 3402 Args: 3403 user: User ID (`usr_...`) for user-scoped tasks. 3404 input: Request body. 3405 input.agent: Explicit acting agent for privileged callers. 3406 input.description: Initial task description. 3407 input.epic: Initial epic grouping. 3408 input.name: Initial task name. 3409 input.org: Explicit organization for privileged callers. 3410 input.source_id: Source identity, for example owner/repo#123. 3411 input.source_scope: Source scope, for example github. 3412 input.source_type: Source type, for example pull_request. 3413 input.status: Initial task status. 3414 input.team: Team owner. 3415 3416 Returns: 3417 The task and whether this request created it. 3418 """ 3419 return await self._http.request( 3420 f"/api/v1/users/{user}/tasks/by-source", 3421 method="PUT", 3422 body=input, 3423 response_type=TaskEnsureResult, 3424 ) 3425 3426 async def ready( 3427 self, 3428 user: str, 3429 *, 3430 team: str | None = None, 3431 org: str | None = None, 3432 explain: bool | None = None, 3433 assigned_to_me: bool | None = None, 3434 source_scope: str | None = None, 3435 source_type: str | None = None, 3436 source_id: str | None = None, 3437 epic: str | None = None, 3438 limit: int | None = None, 3439 after_cursor: str | None = None, 3440 ) -> UserTaskReadyResponse: 3441 """ 3442 List an owner's ready tasks 3443 Returns open tasks with no unfinished blockers and no active session lease. 3444 Readiness is calculated by the server from the current task projection. It is 3445 a snapshot, not a reservation; claim a task lease before starting work. 3446 Results are ordered by priority (0, the most urgent, first), then oldest 3447 first, so the first page is always the most urgent ready work. 3448 Pass `explain=true` to include every open task with a stable readiness reason. 3449 3450 Args: 3451 user: User ID (`usr_...`) for user-scoped tasks. 3452 team: Team ID (`tem_...`) owning the tasks. 3453 org: Optional organization context for privileged callers. 3454 explain: Include blocked and actively leased open tasks with exclusion reasons. 3455 assigned_to_me: Only include tasks assigned to the authenticated user. 3456 source_scope: Only include tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 3457 source_type: Only include tasks whose source matches this object kind. 3458 source_id: Only include tasks whose source matches this object identity. 3459 epic: Only include tasks with this exact epic label. 3460 limit: Maximum number of readiness entries to return. Capped at 100. 3461 after_cursor: Opaque cursor returned by the previous page. 3462 3463 Returns: 3464 Successful response 3465 """ 3466 query: dict[str, object] = {} 3467 if team is not None: 3468 query["team"] = team 3469 if org is not None: 3470 query["org"] = org 3471 if explain is not None: 3472 query["explain"] = explain 3473 if assigned_to_me is not None: 3474 query["assigned_to_me"] = assigned_to_me 3475 if source_scope is not None: 3476 query["source_scope"] = source_scope 3477 if source_type is not None: 3478 query["source_type"] = source_type 3479 if source_id is not None: 3480 query["source_id"] = source_id 3481 if epic is not None: 3482 query["epic"] = epic 3483 if limit is not None: 3484 query["limit"] = limit 3485 if after_cursor is not None: 3486 query["after_cursor"] = after_cursor 3487 return await self._http.request( 3488 f"/api/v1/users/{user}/tasks/ready", 3489 query=query, 3490 response_type=UserTaskReadyResponse, 3491 ) 3492 3493 async def search( 3494 self, 3495 user: str, 3496 *, 3497 team: str | None = None, 3498 org: str | None = None, 3499 q: str | None = None, 3500 query: str | None = None, 3501 status: str | None = None, 3502 owner_user: str | None = None, 3503 owner_agent: str | None = None, 3504 priority: int | None = None, 3505 tag: str | None = None, 3506 parent: str | None = None, 3507 source_scope: str | None = None, 3508 source_type: str | None = None, 3509 source_id: str | None = None, 3510 epic: str | None = None, 3511 limit: int | None = None, 3512 after_cursor: str | None = None, 3513 ) -> UserTaskSearchResponse: 3514 """ 3515 Search an owner's tasks 3516 Performs a full-text search over tasks owned by the specified user or team and returns 3517 matching results. Combine `q` with the optional filters to narrow the result set 3518 further. When no query is provided, the endpoint behaves like a filtered list. 3519 The `query` field in the response echoes the effective search query. 3520 User-authenticated callers may search their personal tasks or tasks for teams 3521 they have joined. Privileged callers provide the owner in the route; the owner's 3522 organization is implied by that principal. An explicit `org` is optional and, 3523 when set, must match the owner's organization. 3524 3525 Args: 3526 user: User ID (`usr_...`) for user-scoped tasks. 3527 team: Team ID (`tem_...`). Only tasks belonging to this team are searched. 3528 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. 3529 q: Full-text search query matched against task names and descriptions. Takes precedence over `query` when both are provided. 3530 query: Alias for `q`. Use `q` when possible; this parameter exists for compatibility. 3531 status: Filter results by status. One of `"open"`, `"in_progress"`, `"in_review"`, or `"done"`. Omit to include all statuses. 3532 owner_user: Restrict results to tasks assigned to the user with this public ID (`usr_...`). 3533 owner_agent: Restrict results to tasks assigned to the agent with this public ID (`agi_...`). 3534 priority: Filter results by priority, from 0 (highest) to 4 (lowest). 3535 tag: Return only tasks carrying this tag (matched against the canonical lowercase form). 3536 parent: Return only subtasks of the given task (`tsk_...`), or pass `none` to return only top-level tasks. 3537 source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 3538 source_type: Return only tasks whose source matches this object kind. 3539 source_id: Return only tasks whose source matches this object identity. 3540 epic: Return only tasks with this exact epic label. 3541 limit: Maximum number of tasks to return. Capped at 100. 3542 after_cursor: Opaque cursor returned by the previous page. 3543 3544 Returns: 3545 Successful response 3546 """ 3547 query: dict[str, object] = {} 3548 if team is not None: 3549 query["team"] = team 3550 if org is not None: 3551 query["org"] = org 3552 if q is not None: 3553 query["q"] = q 3554 if query is not None: 3555 query["query"] = query 3556 if status is not None: 3557 query["status"] = status 3558 if owner_user is not None: 3559 query["owner_user"] = owner_user 3560 if owner_agent is not None: 3561 query["owner_agent"] = owner_agent 3562 if priority is not None: 3563 query["priority"] = priority 3564 if tag is not None: 3565 query["tag"] = tag 3566 if parent is not None: 3567 query["parent"] = parent 3568 if source_scope is not None: 3569 query["source_scope"] = source_scope 3570 if source_type is not None: 3571 query["source_type"] = source_type 3572 if source_id is not None: 3573 query["source_id"] = source_id 3574 if epic is not None: 3575 query["epic"] = epic 3576 if limit is not None: 3577 query["limit"] = limit 3578 if after_cursor is not None: 3579 query["after_cursor"] = after_cursor 3580 return await self._http.request( 3581 f"/api/v1/users/{user}/tasks/search", 3582 query=query, 3583 response_type=UserTaskSearchResponse, 3584 ) 3585 3586 3587class AsyncUserThreadResource: 3588 def __init__(self, http: HttpClient): 3589 self._http = http 3590 3591 async def list( 3592 self, 3593 user: str, 3594 *, 3595 agent: builtins.list[str] | None = None, 3596 filter: builtins.list[dict[str, Any]] | None = None, 3597 ) -> UserThreadListResponse: 3598 """ 3599 List threads for a user 3600 Returns all threads visible to the specified user. The authenticated caller must 3601 have access to the target user's account; a 403 is returned otherwise. 3602 Pass one or more `agent` IDs to narrow results to threads where at least one of 3603 the listed agents is also a member useful for displaying every thread a user 3604 shares with a particular agent. Pass one or more `filter` objects to narrow 3605 results by thread metadata key/value pairs. Both narrowings may be combined in 3606 a single request. 3607 Results are returned as a flat array; no cursor-based pagination is applied. 3608 Threads are ordered with default threads first, then by most recent activity 3609 (newest first), each carrying a `last_activity` timestamp. 3610 3611 Args: 3612 user: User ID (`usr_...`) whose threads should be listed. 3613 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. 3614 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. 3615 3616 Returns: 3617 Successful response 3618 """ 3619 query: dict[str, object] = {} 3620 if agent is not None: 3621 query["agent"] = agent 3622 if filter is not None: 3623 query["filter"] = filter 3624 return await self._http.request( 3625 f"/api/v1/users/{user}/threads", 3626 query=query, 3627 response_type=UserThreadListResponse, 3628 ) 3629 3630 async def create(self, user: str, input: UserThreadCreateInput) -> Thread: 3631 """ 3632 Create a thread for a user 3633 Creates a new thread owned by the specified user. The authenticated caller must 3634 have access to the target user's account; a 403 is returned otherwise. 3635 An automatic welcome message is sent into the thread upon creation unless 3636 `skip_welcome_message` is set to `true`. The thread is immediately visible to 3637 the owning user and any members added at creation time. 3638 3639 Args: 3640 user: User ID (`usr_...`) whose threads should be listed. 3641 input: Request body. 3642 input.skip_welcome_message: When `true`, suppresses the automatic welcome message that is otherwise sent into the thread on creation. Defaults to `false`. 3643 input.thread: Attributes for the new thread. See ThreadCreateParams for the full set of accepted fields. 3644 3645 Returns: 3646 The newly created thread object. 3647 """ 3648 return await self._http.request( 3649 f"/api/v1/users/{user}/threads", 3650 method="POST", 3651 body=input, 3652 response_type=Thread, 3653 ) 3654 3655 3656class AsyncTokenResource: 3657 def __init__(self, http: HttpClient): 3658 self._http = http 3659 3660 async def list(self, user: str) -> TokenListResponse: 3661 """ 3662 List personal access tokens 3663 Returns all access tokens associated with the authenticated user, including 3664 active and revoked tokens. Tokens are returned without their raw JWT values 3665 the plaintext JWT is only available at creation time. 3666 The caller must be the user identified by `user` and must present a 3667 first-party session (or a `full_access` access token). 3668 3669 Args: 3670 user: User ID (`usr_...`) or `me` for the authenticated user. 3671 3672 Returns: 3673 Successful response 3674 """ 3675 return await self._http.request( 3676 f"/api/v1/users/{user}/tokens", 3677 response_type=TokenListResponse, 3678 ) 3679 3680 async def create(self, user: str, input: TokenCreateInput) -> SystemAccessToken: 3681 """ 3682 Create a personal access token 3683 Issues a new long-lived access token for the authenticated user. The raw 3684 JWT is returned in the `token` field of the response exactly once and 3685 cannot be retrieved again store it securely immediately after creation. 3686 `scopes` is optional. When omitted the token receives `full_access`. 3687 Known catalog scopes (for example `profile`) restrict the token through 3688 the same `ScopeGuard` used by OAuth. 3689 `expires_in_days` is optional and must be one of `7`, `30`, `60`, `90`, 3690 or `365`. When omitted the token lasts 30 days. Each user may hold at 3691 most 50 active tokens; exceeding that limit returns 429. 3692 The caller must be the user identified by `user` and must present a 3693 first-party session (or a `full_access` access token). A restricted 3694 access token cannot mint another token. 3695 3696 Args: 3697 user: User ID (`usr_...`) or `me` for the authenticated user. 3698 input: Request body. 3699 input.expires_in_days: Lifetime in days. One of `7`, `30`, `60`, `90`, or `365`. Defaults to `30`. 3700 input.name: Human-readable label for the token (e.g. `"Codex MCP"`). Stored as metadata only. 3701 input.scopes: Optional OAuth scopes to stamp on the token. Omit for `full_access`. 3702 3703 Returns: 3704 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. 3705 """ 3706 return await self._http.request( 3707 f"/api/v1/users/{user}/tokens", 3708 method="POST", 3709 body=input, 3710 response_type=SystemAccessToken, 3711 ) 3712 3713 async def delete(self, user: str, token: str) -> SystemAccessToken: 3714 """ 3715 Revoke a personal access token 3716 Permanently revokes the specified access token belonging to the 3717 authenticated user. Once revoked, the token is immediately rejected by 3718 all API endpoints and cannot be reinstated. The token record is retained 3719 and returned in the response with `revoked_at` populated. 3720 The caller must be the user identified by `user` and must present a 3721 first-party session (or a `full_access` access token). Returns 404 if 3722 the token does not exist or does not belong to the caller. 3723 3724 Args: 3725 user: User ID (`usr_...`) or `me` for the authenticated user. 3726 token: Access token ID (`sat_...`). Must belong to the authenticated user. 3727 3728 Returns: 3729 The revoked access token. The `revoked_at` field is populated with the time of revocation. 3730 """ 3731 return await self._http.request( 3732 f"/api/v1/users/{user}/tokens/{token}", 3733 method="DELETE", 3734 response_type=SystemAccessToken, 3735 ) 3736 3737 3738class AsyncUserResource: 3739 def __init__(self, http: HttpClient): 3740 self._http = http 3741 self.integrations = AsyncIntegrationResource(http) 3742 self.ssh_keys = AsyncUserSshKeyResource(http) 3743 self.tasks = AsyncUserTaskResource(http) 3744 self.threads = AsyncUserThreadResource(http) 3745 self.tokens = AsyncTokenResource(http) 3746 3747 async def me(self, *, entitlement: list[str] | None = None) -> CurrentUser: 3748 """ 3749 Retrieve the current user 3750 Returns the user associated with the authenticated session or bearer 3751 token. This is the canonical way to resolve "who am I?" after 3752 authentication. 3753 The response includes the user's profile, notification settings, and 3754 profile picture, along with the app, organization, and sandbox the 3755 token is scoped to and their display names enough to establish full 3756 session context in a single call. Unauthenticated requests return 401. 3757 3758 Args: 3759 entitlement: Entitlement catalog keys to evaluate. Supplying this expansion additionally requires `entitlements:read`. 3760 3761 Returns: 3762 The authenticated user object. 3763 """ 3764 query: dict[str, object] = {} 3765 if entitlement is not None: 3766 query["entitlement"] = entitlement 3767 return await self._http.request("/api/v1/users/me", query=query, response_type=CurrentUser) 3768 3769 async def get(self, user: str) -> User: 3770 """ 3771 Retrieve a user by ID 3772 Returns the user identified by `user`. The authenticated user must share 3773 an organization or at least one team with the target user; other requests 3774 are rejected with 403. 3775 A user may always retrieve their own profile with this endpoint. Use the 3776 `GET /users/me` endpoint as a convenience alias for retrieving the 3777 authenticated user without specifying an ID. 3778 3779 Args: 3780 user: User ID (`usr_...`) of the user to retrieve. 3781 3782 Returns: 3783 The requested user object. 3784 """ 3785 return await self._http.request(f"/api/v1/users/{user}", response_type=User) 3786 3787 async def artifacts( 3788 self, user: str, *, group_key: str | None = None, group_key_prefix: str | None = None 3789 ) -> UserArtifactsResponse: 3790 """ 3791 List a user's artifacts 3792 Returns all artifacts owned by the specified user. Artifacts represent 3793 AI-generated or user-uploaded files associated with agent sessions, 3794 threads, or sandboxes such as images, documents, and code outputs. 3795 The authenticated user must be requesting their own artifacts or must 3796 have administrative access. Attempting to list artifacts for a user 3797 the caller is not authorized to access returns 403. 3798 Results are returned in a single page without cursor pagination. Each 3799 artifact in the response reflects the state of its current version, 3800 including a short-lived signed `file_url` for direct download. 3801 3802 Args: 3803 user: User ID (`usr_...`). The authenticated user must be this user or have access to their artifacts. 3804 group_key: Case-sensitive exact group key. Mutually exclusive with group_key_prefix; null keys do not match. 3805 group_key_prefix: Nonempty case-sensitive literal prefix (percent, underscore and backslash are literal). Mutually exclusive with group_key. 3806 3807 Returns: 3808 Successful response 3809 """ 3810 query: dict[str, object] = {} 3811 if group_key is not None: 3812 query["group_key"] = group_key 3813 if group_key_prefix is not None: 3814 query["group_key_prefix"] = group_key_prefix 3815 return await self._http.request( 3816 f"/api/v1/users/{user}/artifacts", 3817 query=query, 3818 response_type=UserArtifactsResponse, 3819 ) 3820 3821 async def invites(self, user: str, input: UserInvitesInput) -> UserInvite: 3822 """ 3823 Create a user invite 3824 Creates a new invite for the authenticated user. The invite can optionally be 3825 scoped to a specific thread, a persona, or carry arbitrary metadata. The 3826 caller receives the new invite object at HTTP 201. 3827 The invite key is always generated server-side (192-bit URL-safe random 3828 string) and cannot be supplied by the caller. 3829 The path `:user` must match the authenticated user. If a `thread_id` is 3830 provided, the authenticated user must have permission to invite others to that 3831 thread; team threads are not supported and return an error. Supplying a 3832 `thread_id` that does not exist or that belongs to a different user returns 3833 an error. If a key collision occurs during creation the call returns a 409 3834 conflict simply retry to generate a new key. 3835 3836 Args: 3837 user: User ID (`usr_...`). Must match the authenticated user. 3838 input: Request body. 3839 input.invite: Parameters for the new invite. See the UserInviteCreateParams schema for field details. 3840 3841 Returns: 3842 The newly created invite object. 3843 """ 3844 return await self._http.request( 3845 f"/api/v1/users/{user}/invites", 3846 method="POST", 3847 body=input, 3848 response_type=UserInvite, 3849 ) 3850 3851 async def orgs(self, user: str) -> UserOrgsResponse: 3852 """ 3853 List organizations for a user 3854 Returns the organizations the specified user belongs to. A user can belong 3855 to at most one organization, so the `data` array contains either zero or one 3856 items. 3857 The authenticated viewer must have permission to inspect the target user. 3858 Returns an empty `data` array when the user has no organization membership. 3859 3860 Args: 3861 user: User ID (`usr_...`) whose organization membership you want to retrieve. 3862 3863 Returns: 3864 Successful response 3865 """ 3866 return await self._http.request( 3867 f"/api/v1/users/{user}/orgs", 3868 response_type=UserOrgsResponse, 3869 ) 3870 3871 async def profile(self, user: str, input: UserProfileInput) -> User: 3872 """ 3873 Update the current user's profile 3874 Updates one or more profile fields for the authenticated user. All 3875 fields are optional; omit any you do not want to change. 3876 When `profile_picture` is supplied, the image is uploaded and replaces 3877 the existing picture. The previous picture is deleted after the new one 3878 is stored. Image upload failures return 422 without modifying other 3879 profile fields. 3880 3881 Args: 3882 user: User ID (`usr_...`) or `"me"` for the authenticated user. 3883 input: Request body. 3884 input.alias: Short display alias shown in place of the full name in compact UI contexts. 3885 input.clear_full_name: Set to true to clear the optional display name. Cannot be combined with full_name. 3886 input.clear_profile_picture: Set to true to remove the current profile picture. Cannot be combined with profile_picture. 3887 input.full_name: Updated display name for the user. 3888 input.metadata: Arbitrary key-value metadata to associate with the user. Existing keys are merged; pass `null` for a key to remove it. 3889 input.profile_picture: New profile picture to upload as a base64-encoded image. Replaces any existing picture. 3890 3891 Returns: 3892 The user object with updated profile fields. 3893 """ 3894 return await self._http.request( 3895 f"/api/v1/users/{user}/profile", 3896 method="PUT", 3897 body=input, 3898 response_type=User, 3899 ) 3900 3901 async def task_epics( 3902 self, 3903 user: str, 3904 *, 3905 team: str | None = None, 3906 org: str | None = None, 3907 source_scope: str | None = None, 3908 source_type: str | None = None, 3909 source_id: str | None = None, 3910 top_priority: int | None = None, 3911 include_closed: bool | None = None, 3912 limit: int | None = None, 3913 after_cursor: str | None = None, 3914 ) -> UserTaskEpicsResponse: 3915 """ 3916 List an owner's epic summaries 3917 Groups tasks by their exact epic label, ordered by label. Closed tasks include cancelled tasks, but cancelled prerequisites still block. Source filters select the tasks summarized; blockers outside that selection still affect readiness. Root ranking is capped per epic and root_blockers_partial is true when that graph is truncated. No epic entity is created. 3918 3919 Args: 3920 source_scope: Exact source scope; supply all three source fields. 3921 source_type: Exact source type. 3922 source_id: Exact source ID. 3923 top_priority: Exact highest open priority, from 0 to 4. 3924 include_closed: Include epics with no non-closed tasks; defaults to false. 3925 limit: Maximum epics; defaults to 50, capped at 100. 3926 after_cursor: Opaque forward cursor from the preceding page. 3927 3928 Returns: 3929 Successful response 3930 """ 3931 query: dict[str, object] = {} 3932 if team is not None: 3933 query["team"] = team 3934 if org is not None: 3935 query["org"] = org 3936 if source_scope is not None: 3937 query["source_scope"] = source_scope 3938 if source_type is not None: 3939 query["source_type"] = source_type 3940 if source_id is not None: 3941 query["source_id"] = source_id 3942 if top_priority is not None: 3943 query["top_priority"] = top_priority 3944 if include_closed is not None: 3945 query["include_closed"] = include_closed 3946 if limit is not None: 3947 query["limit"] = limit 3948 if after_cursor is not None: 3949 query["after_cursor"] = after_cursor 3950 return await self._http.request( 3951 f"/api/v1/users/{user}/task_epics", 3952 query=query, 3953 response_type=UserTaskEpicsResponse, 3954 ) 3955 3956 3957class IntegrationResource: 3958 def __init__(self, http: SyncHttpClient): 3959 self._http = http 3960 3961 def access_token(self, user: str, provider: str) -> IntegrationAccessTokenResponse: 3962 """ 3963 Retrieve a GitHub integration access token 3964 Returns a valid GitHub access token for one integration owned by the 3965 authenticated user. Expired tokens are refreshed before the response is 3966 returned. 3967 This endpoint accepts the user's own bearer token, or the app's secret key 3968 acting server-to-server for one of its users. Developer, agent, team, and 3969 cross-user viewers cannot retrieve the credential. Responses are marked 3970 `Cache-Control: no-store`. 3971 3972 Args: 3973 user: User ID (`usr_...`). The authenticated user, or a user of the app whose secret key is presented. 3974 provider: Integration provider. Only `github` is accepted. 3975 3976 Returns: 3977 Successful response 3978 """ 3979 return self._http.request( 3980 f"/api/v1/users/{user}/integrations/{provider}/access_token", 3981 response_type=IntegrationAccessTokenResponse, 3982 ) 3983 3984 3985class UserSshKeyResource: 3986 def __init__(self, http: SyncHttpClient): 3987 self._http = http 3988 3989 def list( 3990 self, user: str, *, limit: int | None = None, after_cursor: str | None = None 3991 ) -> UserSshKeyListResponse: 3992 """ 3993 List registered SSH keys 3994 Returns a cursor-paginated page of SSH-key metadata for the authenticated user. 3995 3996 Args: 3997 user: User ID (`usr_...`) or `me`. 3998 limit: Maximum keys per page. Defaults to 50; maximum is 100. 3999 after_cursor: Opaque cursor for the next page of older keys. 4000 4001 Returns: 4002 Successful response 4003 """ 4004 query: dict[str, object] = {} 4005 if limit is not None: 4006 query["limit"] = limit 4007 if after_cursor is not None: 4008 query["after_cursor"] = after_cursor 4009 return self._http.request( 4010 f"/api/v1/users/{user}/ssh_keys", 4011 query=query, 4012 response_type=UserSshKeyListResponse, 4013 ) 4014 4015 def create(self, user: str, input: UserSshKeyCreateInput) -> UserSSHKey: 4016 """ 4017 Register an SSH public key 4018 Registers one comment-free Ed25519 public key for Git-over-SSH. The key is 4019 encrypted before storage; responses expose only its label, algorithm and 4020 OpenSSH SHA-256 fingerprint. 4021 The caller must be the user named by `user` and must present a first-party 4022 session or a `full_access` personal access token. 4023 4024 Args: 4025 user: User ID (`usr_...`) or `me`. 4026 input: Request body. 4027 input.label: A label such as `Work laptop`. 4028 input.public_key: One `ssh-ed25519 <base64>` public key without options or a comment. 4029 4030 Returns: 4031 Metadata for the registered key; no key material. 4032 """ 4033 return self._http.request( 4034 f"/api/v1/users/{user}/ssh_keys", 4035 method="POST", 4036 body=input, 4037 response_type=UserSSHKey, 4038 ) 4039 4040 4041class UserTaskResource: 4042 def __init__(self, http: SyncHttpClient): 4043 self._http = http 4044 4045 def list( 4046 self, 4047 user: str, 4048 *, 4049 team: str | None = None, 4050 org: str | None = None, 4051 status: str | None = None, 4052 owner_user: str | None = None, 4053 owner_agent: str | None = None, 4054 priority: int | None = None, 4055 tag: str | None = None, 4056 parent: str | None = None, 4057 source_scope: str | None = None, 4058 source_type: str | None = None, 4059 source_id: str | None = None, 4060 epic: str | None = None, 4061 search: str | None = None, 4062 sort: str | None = None, 4063 order: str | None = None, 4064 due_before: str | None = None, 4065 due_after: str | None = None, 4066 overdue: bool | None = None, 4067 ready: bool | None = None, 4068 attention: bool | None = None, 4069 limit: int | None = None, 4070 after_cursor: str | None = None, 4071 ) -> UserTaskListResponse: 4072 """ 4073 List an owner's tasks 4074 Returns tasks owned by the specified user or team. You can narrow results using the 4075 optional filters below. By default results are returned in reverse chronological 4076 order (most recently created first); use `sort` and `order` to sort by due date or 4077 priority instead. 4078 User-authenticated callers may list their personal tasks or tasks for teams they 4079 have joined. Privileged callers provide the owner in the route; the owner's 4080 organization is implied by that principal. An explicit `org` is optional and, 4081 when set, must match the owner's organization. 4082 4083 Args: 4084 user: User ID (`usr_...`) for user-scoped tasks. 4085 team: Team ID (`tem_...`). Only tasks belonging to this team are returned. 4086 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. 4087 status: Filter tasks by status. One of `"open"`, `"in_progress"`, `"in_review"`, or `"done"`. Omit to return tasks in all statuses. 4088 owner_user: Filter tasks assigned to a specific user. Provide the user's public ID (`usr_...`). 4089 owner_agent: Filter tasks assigned to a specific agent. Provide the agent's public ID (`agi_...`). 4090 priority: Filter tasks by priority, from 0 (highest) to 4 (lowest). 4091 tag: Return only tasks carrying this tag (matched against the canonical lowercase form). 4092 parent: Return only subtasks of the given task (`tsk_...`), or pass `none` to return only top-level tasks. 4093 source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 4094 source_type: Return only tasks whose source matches this object kind. Must be supplied with the other source filters. 4095 source_id: Return only tasks whose source matches this object identity. Must be supplied with the other source filters. 4096 epic: Return only tasks with this exact epic label. 4097 search: Restrict results to tasks whose name or description contains this string. 4098 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. 4099 order: Sort direction, `"asc"` or `"desc"`. Defaults to `"desc"` for `created` and `"asc"` for `due_date` and `priority`. 4100 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. 4101 due_after: Return only tasks with a due date strictly after this ISO 8601 datetime or date. Tasks without a due date are excluded. 4102 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. 4103 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. 4104 attention: When true, return paused, failed, or in-progress tasks with no lease or a past lease expiry. 4105 limit: Maximum number of tasks to return. Capped at 100. 4106 after_cursor: Opaque cursor returned by the previous page. 4107 4108 Returns: 4109 Successful response 4110 """ 4111 query: dict[str, object] = {} 4112 if team is not None: 4113 query["team"] = team 4114 if org is not None: 4115 query["org"] = org 4116 if status is not None: 4117 query["status"] = status 4118 if owner_user is not None: 4119 query["owner_user"] = owner_user 4120 if owner_agent is not None: 4121 query["owner_agent"] = owner_agent 4122 if priority is not None: 4123 query["priority"] = priority 4124 if tag is not None: 4125 query["tag"] = tag 4126 if parent is not None: 4127 query["parent"] = parent 4128 if source_scope is not None: 4129 query["source_scope"] = source_scope 4130 if source_type is not None: 4131 query["source_type"] = source_type 4132 if source_id is not None: 4133 query["source_id"] = source_id 4134 if epic is not None: 4135 query["epic"] = epic 4136 if search is not None: 4137 query["search"] = search 4138 if sort is not None: 4139 query["sort"] = sort 4140 if order is not None: 4141 query["order"] = order 4142 if due_before is not None: 4143 query["due_before"] = due_before 4144 if due_after is not None: 4145 query["due_after"] = due_after 4146 if overdue is not None: 4147 query["overdue"] = overdue 4148 if ready is not None: 4149 query["ready"] = ready 4150 if attention is not None: 4151 query["attention"] = attention 4152 if limit is not None: 4153 query["limit"] = limit 4154 if after_cursor is not None: 4155 query["after_cursor"] = after_cursor 4156 return self._http.request( 4157 f"/api/v1/users/{user}/tasks", 4158 query=query, 4159 response_type=UserTaskListResponse, 4160 ) 4161 4162 def create(self, user: str, input: UserTaskCreateInput) -> Task: 4163 """ 4164 Create a task for an owner 4165 Creates a new task owned by the specified user or team and returns the full 4166 task object. User-authenticated calls are attributed to the authenticated 4167 user or agent. App-scoped developer and server-to-server callers must provide 4168 the task's explicit `org` scope and an explicit `user` or `agent` actor for 4169 team tasks; a user-owned task reuses the user in the route unless an explicit 4170 agent is supplied. Every referenced principal is validated against the app, 4171 owner, and team membership before creation. 4172 4173 Args: 4174 user: User ID (`usr_...`) for user-scoped tasks. 4175 input: Request body. 4176 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. 4177 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. 4178 input.task: Attributes for the task to create. `name` is required; all other fields are optional. 4179 input.team: Team ID (`tem_...`). The task will be owned by this team. 4180 4181 Returns: 4182 The newly created task. 4183 """ 4184 return self._http.request( 4185 f"/api/v1/users/{user}/tasks", 4186 method="POST", 4187 body=input, 4188 response_type=Task, 4189 ) 4190 4191 def blocker_cycles( 4192 self, 4193 user: str, 4194 *, 4195 team: str | None = None, 4196 org: str | None = None, 4197 limit: int | None = None, 4198 after_cursor: str | None = None, 4199 ) -> UserTaskBlockerCyclesResponse: 4200 """ 4201 List task blocker cycles 4202 Runs an on-demand diagnostic over unfinished tasks owned by the specified 4203 team or user and returns a forward cursor-paginated page of complete cyclic 4204 blocker components. Detection is bounded to owners with at most 100 4205 unfinished tasks. This endpoint is read-only: cycles do not prevent task 4206 updates, lease acquisition, or completion. 4207 4208 Args: 4209 user: User ID (`usr_...`) for user-scoped tasks. 4210 team: Team ID (`tem_...`) owning the tasks. 4211 org: Optional organization context for privileged callers. 4212 limit: Maximum cycle components to return. Defaults to 50; maximum is 100. 4213 after_cursor: Opaque cursor returned by the preceding page. 4214 4215 Returns: 4216 Successful response 4217 """ 4218 query: dict[str, object] = {} 4219 if team is not None: 4220 query["team"] = team 4221 if org is not None: 4222 query["org"] = org 4223 if limit is not None: 4224 query["limit"] = limit 4225 if after_cursor is not None: 4226 query["after_cursor"] = after_cursor 4227 return self._http.request( 4228 f"/api/v1/users/{user}/tasks/blocker_cycles", 4229 query=query, 4230 response_type=UserTaskBlockerCyclesResponse, 4231 ) 4232 4233 def by_source(self, user: str, input: UserTaskBySourceInput) -> TaskEnsureResult: 4234 """ 4235 Find or create a task by source 4236 Atomically creates one task per owner, tenant and source. Retries return the current task without updating it. Historical tasks created through ordinary create are not adopted. 4237 4238 Args: 4239 user: User ID (`usr_...`) for user-scoped tasks. 4240 input: Request body. 4241 input.agent: Explicit acting agent for privileged callers. 4242 input.description: Initial task description. 4243 input.epic: Initial epic grouping. 4244 input.name: Initial task name. 4245 input.org: Explicit organization for privileged callers. 4246 input.source_id: Source identity, for example owner/repo#123. 4247 input.source_scope: Source scope, for example github. 4248 input.source_type: Source type, for example pull_request. 4249 input.status: Initial task status. 4250 input.team: Team owner. 4251 4252 Returns: 4253 The task and whether this request created it. 4254 """ 4255 return self._http.request( 4256 f"/api/v1/users/{user}/tasks/by-source", 4257 method="PUT", 4258 body=input, 4259 response_type=TaskEnsureResult, 4260 ) 4261 4262 def ready( 4263 self, 4264 user: str, 4265 *, 4266 team: str | None = None, 4267 org: str | None = None, 4268 explain: bool | None = None, 4269 assigned_to_me: bool | None = None, 4270 source_scope: str | None = None, 4271 source_type: str | None = None, 4272 source_id: str | None = None, 4273 epic: str | None = None, 4274 limit: int | None = None, 4275 after_cursor: str | None = None, 4276 ) -> UserTaskReadyResponse: 4277 """ 4278 List an owner's ready tasks 4279 Returns open tasks with no unfinished blockers and no active session lease. 4280 Readiness is calculated by the server from the current task projection. It is 4281 a snapshot, not a reservation; claim a task lease before starting work. 4282 Results are ordered by priority (0, the most urgent, first), then oldest 4283 first, so the first page is always the most urgent ready work. 4284 Pass `explain=true` to include every open task with a stable readiness reason. 4285 4286 Args: 4287 user: User ID (`usr_...`) for user-scoped tasks. 4288 team: Team ID (`tem_...`) owning the tasks. 4289 org: Optional organization context for privileged callers. 4290 explain: Include blocked and actively leased open tasks with exclusion reasons. 4291 assigned_to_me: Only include tasks assigned to the authenticated user. 4292 source_scope: Only include tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 4293 source_type: Only include tasks whose source matches this object kind. 4294 source_id: Only include tasks whose source matches this object identity. 4295 epic: Only include tasks with this exact epic label. 4296 limit: Maximum number of readiness entries to return. Capped at 100. 4297 after_cursor: Opaque cursor returned by the previous page. 4298 4299 Returns: 4300 Successful response 4301 """ 4302 query: dict[str, object] = {} 4303 if team is not None: 4304 query["team"] = team 4305 if org is not None: 4306 query["org"] = org 4307 if explain is not None: 4308 query["explain"] = explain 4309 if assigned_to_me is not None: 4310 query["assigned_to_me"] = assigned_to_me 4311 if source_scope is not None: 4312 query["source_scope"] = source_scope 4313 if source_type is not None: 4314 query["source_type"] = source_type 4315 if source_id is not None: 4316 query["source_id"] = source_id 4317 if epic is not None: 4318 query["epic"] = epic 4319 if limit is not None: 4320 query["limit"] = limit 4321 if after_cursor is not None: 4322 query["after_cursor"] = after_cursor 4323 return self._http.request( 4324 f"/api/v1/users/{user}/tasks/ready", 4325 query=query, 4326 response_type=UserTaskReadyResponse, 4327 ) 4328 4329 def search( 4330 self, 4331 user: str, 4332 *, 4333 team: str | None = None, 4334 org: str | None = None, 4335 q: str | None = None, 4336 query: str | None = None, 4337 status: str | None = None, 4338 owner_user: str | None = None, 4339 owner_agent: str | None = None, 4340 priority: int | None = None, 4341 tag: str | None = None, 4342 parent: str | None = None, 4343 source_scope: str | None = None, 4344 source_type: str | None = None, 4345 source_id: str | None = None, 4346 epic: str | None = None, 4347 limit: int | None = None, 4348 after_cursor: str | None = None, 4349 ) -> UserTaskSearchResponse: 4350 """ 4351 Search an owner's tasks 4352 Performs a full-text search over tasks owned by the specified user or team and returns 4353 matching results. Combine `q` with the optional filters to narrow the result set 4354 further. When no query is provided, the endpoint behaves like a filtered list. 4355 The `query` field in the response echoes the effective search query. 4356 User-authenticated callers may search their personal tasks or tasks for teams 4357 they have joined. Privileged callers provide the owner in the route; the owner's 4358 organization is implied by that principal. An explicit `org` is optional and, 4359 when set, must match the owner's organization. 4360 4361 Args: 4362 user: User ID (`usr_...`) for user-scoped tasks. 4363 team: Team ID (`tem_...`). Only tasks belonging to this team are searched. 4364 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. 4365 q: Full-text search query matched against task names and descriptions. Takes precedence over `query` when both are provided. 4366 query: Alias for `q`. Use `q` when possible; this parameter exists for compatibility. 4367 status: Filter results by status. One of `"open"`, `"in_progress"`, `"in_review"`, or `"done"`. Omit to include all statuses. 4368 owner_user: Restrict results to tasks assigned to the user with this public ID (`usr_...`). 4369 owner_agent: Restrict results to tasks assigned to the agent with this public ID (`agi_...`). 4370 priority: Filter results by priority, from 0 (highest) to 4 (lowest). 4371 tag: Return only tasks carrying this tag (matched against the canonical lowercase form). 4372 parent: Return only subtasks of the given task (`tsk_...`), or pass `none` to return only top-level tasks. 4373 source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 4374 source_type: Return only tasks whose source matches this object kind. 4375 source_id: Return only tasks whose source matches this object identity. 4376 epic: Return only tasks with this exact epic label. 4377 limit: Maximum number of tasks to return. Capped at 100. 4378 after_cursor: Opaque cursor returned by the previous page. 4379 4380 Returns: 4381 Successful response 4382 """ 4383 query: dict[str, object] = {} 4384 if team is not None: 4385 query["team"] = team 4386 if org is not None: 4387 query["org"] = org 4388 if q is not None: 4389 query["q"] = q 4390 if query is not None: 4391 query["query"] = query 4392 if status is not None: 4393 query["status"] = status 4394 if owner_user is not None: 4395 query["owner_user"] = owner_user 4396 if owner_agent is not None: 4397 query["owner_agent"] = owner_agent 4398 if priority is not None: 4399 query["priority"] = priority 4400 if tag is not None: 4401 query["tag"] = tag 4402 if parent is not None: 4403 query["parent"] = parent 4404 if source_scope is not None: 4405 query["source_scope"] = source_scope 4406 if source_type is not None: 4407 query["source_type"] = source_type 4408 if source_id is not None: 4409 query["source_id"] = source_id 4410 if epic is not None: 4411 query["epic"] = epic 4412 if limit is not None: 4413 query["limit"] = limit 4414 if after_cursor is not None: 4415 query["after_cursor"] = after_cursor 4416 return self._http.request( 4417 f"/api/v1/users/{user}/tasks/search", 4418 query=query, 4419 response_type=UserTaskSearchResponse, 4420 ) 4421 4422 4423class UserThreadResource: 4424 def __init__(self, http: SyncHttpClient): 4425 self._http = http 4426 4427 def list( 4428 self, 4429 user: str, 4430 *, 4431 agent: builtins.list[str] | None = None, 4432 filter: builtins.list[dict[str, Any]] | None = None, 4433 ) -> UserThreadListResponse: 4434 """ 4435 List threads for a user 4436 Returns all threads visible to the specified user. The authenticated caller must 4437 have access to the target user's account; a 403 is returned otherwise. 4438 Pass one or more `agent` IDs to narrow results to threads where at least one of 4439 the listed agents is also a member useful for displaying every thread a user 4440 shares with a particular agent. Pass one or more `filter` objects to narrow 4441 results by thread metadata key/value pairs. Both narrowings may be combined in 4442 a single request. 4443 Results are returned as a flat array; no cursor-based pagination is applied. 4444 Threads are ordered with default threads first, then by most recent activity 4445 (newest first), each carrying a `last_activity` timestamp. 4446 4447 Args: 4448 user: User ID (`usr_...`) whose threads should be listed. 4449 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. 4450 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. 4451 4452 Returns: 4453 Successful response 4454 """ 4455 query: dict[str, object] = {} 4456 if agent is not None: 4457 query["agent"] = agent 4458 if filter is not None: 4459 query["filter"] = filter 4460 return self._http.request( 4461 f"/api/v1/users/{user}/threads", 4462 query=query, 4463 response_type=UserThreadListResponse, 4464 ) 4465 4466 def create(self, user: str, input: UserThreadCreateInput) -> Thread: 4467 """ 4468 Create a thread for a user 4469 Creates a new thread owned by the specified user. The authenticated caller must 4470 have access to the target user's account; a 403 is returned otherwise. 4471 An automatic welcome message is sent into the thread upon creation unless 4472 `skip_welcome_message` is set to `true`. The thread is immediately visible to 4473 the owning user and any members added at creation time. 4474 4475 Args: 4476 user: User ID (`usr_...`) whose threads should be listed. 4477 input: Request body. 4478 input.skip_welcome_message: When `true`, suppresses the automatic welcome message that is otherwise sent into the thread on creation. Defaults to `false`. 4479 input.thread: Attributes for the new thread. See ThreadCreateParams for the full set of accepted fields. 4480 4481 Returns: 4482 The newly created thread object. 4483 """ 4484 return self._http.request( 4485 f"/api/v1/users/{user}/threads", 4486 method="POST", 4487 body=input, 4488 response_type=Thread, 4489 ) 4490 4491 4492class TokenResource: 4493 def __init__(self, http: SyncHttpClient): 4494 self._http = http 4495 4496 def list(self, user: str) -> TokenListResponse: 4497 """ 4498 List personal access tokens 4499 Returns all access tokens associated with the authenticated user, including 4500 active and revoked tokens. Tokens are returned without their raw JWT values 4501 the plaintext JWT is only available at creation time. 4502 The caller must be the user identified by `user` and must present a 4503 first-party session (or a `full_access` access token). 4504 4505 Args: 4506 user: User ID (`usr_...`) or `me` for the authenticated user. 4507 4508 Returns: 4509 Successful response 4510 """ 4511 return self._http.request(f"/api/v1/users/{user}/tokens", response_type=TokenListResponse) 4512 4513 def create(self, user: str, input: TokenCreateInput) -> SystemAccessToken: 4514 """ 4515 Create a personal access token 4516 Issues a new long-lived access token for the authenticated user. The raw 4517 JWT is returned in the `token` field of the response exactly once and 4518 cannot be retrieved again store it securely immediately after creation. 4519 `scopes` is optional. When omitted the token receives `full_access`. 4520 Known catalog scopes (for example `profile`) restrict the token through 4521 the same `ScopeGuard` used by OAuth. 4522 `expires_in_days` is optional and must be one of `7`, `30`, `60`, `90`, 4523 or `365`. When omitted the token lasts 30 days. Each user may hold at 4524 most 50 active tokens; exceeding that limit returns 429. 4525 The caller must be the user identified by `user` and must present a 4526 first-party session (or a `full_access` access token). A restricted 4527 access token cannot mint another token. 4528 4529 Args: 4530 user: User ID (`usr_...`) or `me` for the authenticated user. 4531 input: Request body. 4532 input.expires_in_days: Lifetime in days. One of `7`, `30`, `60`, `90`, or `365`. Defaults to `30`. 4533 input.name: Human-readable label for the token (e.g. `"Codex MCP"`). Stored as metadata only. 4534 input.scopes: Optional OAuth scopes to stamp on the token. Omit for `full_access`. 4535 4536 Returns: 4537 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. 4538 """ 4539 return self._http.request( 4540 f"/api/v1/users/{user}/tokens", 4541 method="POST", 4542 body=input, 4543 response_type=SystemAccessToken, 4544 ) 4545 4546 def delete(self, user: str, token: str) -> SystemAccessToken: 4547 """ 4548 Revoke a personal access token 4549 Permanently revokes the specified access token belonging to the 4550 authenticated user. Once revoked, the token is immediately rejected by 4551 all API endpoints and cannot be reinstated. The token record is retained 4552 and returned in the response with `revoked_at` populated. 4553 The caller must be the user identified by `user` and must present a 4554 first-party session (or a `full_access` access token). Returns 404 if 4555 the token does not exist or does not belong to the caller. 4556 4557 Args: 4558 user: User ID (`usr_...`) or `me` for the authenticated user. 4559 token: Access token ID (`sat_...`). Must belong to the authenticated user. 4560 4561 Returns: 4562 The revoked access token. The `revoked_at` field is populated with the time of revocation. 4563 """ 4564 return self._http.request( 4565 f"/api/v1/users/{user}/tokens/{token}", 4566 method="DELETE", 4567 response_type=SystemAccessToken, 4568 ) 4569 4570 4571class UserResource: 4572 def __init__(self, http: SyncHttpClient): 4573 self._http = http 4574 self.integrations = IntegrationResource(http) 4575 self.ssh_keys = UserSshKeyResource(http) 4576 self.tasks = UserTaskResource(http) 4577 self.threads = UserThreadResource(http) 4578 self.tokens = TokenResource(http) 4579 4580 def me(self, *, entitlement: list[str] | None = None) -> CurrentUser: 4581 """ 4582 Retrieve the current user 4583 Returns the user associated with the authenticated session or bearer 4584 token. This is the canonical way to resolve "who am I?" after 4585 authentication. 4586 The response includes the user's profile, notification settings, and 4587 profile picture, along with the app, organization, and sandbox the 4588 token is scoped to and their display names enough to establish full 4589 session context in a single call. Unauthenticated requests return 401. 4590 4591 Args: 4592 entitlement: Entitlement catalog keys to evaluate. Supplying this expansion additionally requires `entitlements:read`. 4593 4594 Returns: 4595 The authenticated user object. 4596 """ 4597 query: dict[str, object] = {} 4598 if entitlement is not None: 4599 query["entitlement"] = entitlement 4600 return self._http.request("/api/v1/users/me", query=query, response_type=CurrentUser) 4601 4602 def get(self, user: str) -> User: 4603 """ 4604 Retrieve a user by ID 4605 Returns the user identified by `user`. The authenticated user must share 4606 an organization or at least one team with the target user; other requests 4607 are rejected with 403. 4608 A user may always retrieve their own profile with this endpoint. Use the 4609 `GET /users/me` endpoint as a convenience alias for retrieving the 4610 authenticated user without specifying an ID. 4611 4612 Args: 4613 user: User ID (`usr_...`) of the user to retrieve. 4614 4615 Returns: 4616 The requested user object. 4617 """ 4618 return self._http.request(f"/api/v1/users/{user}", response_type=User) 4619 4620 def artifacts( 4621 self, user: str, *, group_key: str | None = None, group_key_prefix: str | None = None 4622 ) -> UserArtifactsResponse: 4623 """ 4624 List a user's artifacts 4625 Returns all artifacts owned by the specified user. Artifacts represent 4626 AI-generated or user-uploaded files associated with agent sessions, 4627 threads, or sandboxes such as images, documents, and code outputs. 4628 The authenticated user must be requesting their own artifacts or must 4629 have administrative access. Attempting to list artifacts for a user 4630 the caller is not authorized to access returns 403. 4631 Results are returned in a single page without cursor pagination. Each 4632 artifact in the response reflects the state of its current version, 4633 including a short-lived signed `file_url` for direct download. 4634 4635 Args: 4636 user: User ID (`usr_...`). The authenticated user must be this user or have access to their artifacts. 4637 group_key: Case-sensitive exact group key. Mutually exclusive with group_key_prefix; null keys do not match. 4638 group_key_prefix: Nonempty case-sensitive literal prefix (percent, underscore and backslash are literal). Mutually exclusive with group_key. 4639 4640 Returns: 4641 Successful response 4642 """ 4643 query: dict[str, object] = {} 4644 if group_key is not None: 4645 query["group_key"] = group_key 4646 if group_key_prefix is not None: 4647 query["group_key_prefix"] = group_key_prefix 4648 return self._http.request( 4649 f"/api/v1/users/{user}/artifacts", 4650 query=query, 4651 response_type=UserArtifactsResponse, 4652 ) 4653 4654 def invites(self, user: str, input: UserInvitesInput) -> UserInvite: 4655 """ 4656 Create a user invite 4657 Creates a new invite for the authenticated user. The invite can optionally be 4658 scoped to a specific thread, a persona, or carry arbitrary metadata. The 4659 caller receives the new invite object at HTTP 201. 4660 The invite key is always generated server-side (192-bit URL-safe random 4661 string) and cannot be supplied by the caller. 4662 The path `:user` must match the authenticated user. If a `thread_id` is 4663 provided, the authenticated user must have permission to invite others to that 4664 thread; team threads are not supported and return an error. Supplying a 4665 `thread_id` that does not exist or that belongs to a different user returns 4666 an error. If a key collision occurs during creation the call returns a 409 4667 conflict simply retry to generate a new key. 4668 4669 Args: 4670 user: User ID (`usr_...`). Must match the authenticated user. 4671 input: Request body. 4672 input.invite: Parameters for the new invite. See the UserInviteCreateParams schema for field details. 4673 4674 Returns: 4675 The newly created invite object. 4676 """ 4677 return self._http.request( 4678 f"/api/v1/users/{user}/invites", 4679 method="POST", 4680 body=input, 4681 response_type=UserInvite, 4682 ) 4683 4684 def orgs(self, user: str) -> UserOrgsResponse: 4685 """ 4686 List organizations for a user 4687 Returns the organizations the specified user belongs to. A user can belong 4688 to at most one organization, so the `data` array contains either zero or one 4689 items. 4690 The authenticated viewer must have permission to inspect the target user. 4691 Returns an empty `data` array when the user has no organization membership. 4692 4693 Args: 4694 user: User ID (`usr_...`) whose organization membership you want to retrieve. 4695 4696 Returns: 4697 Successful response 4698 """ 4699 return self._http.request(f"/api/v1/users/{user}/orgs", response_type=UserOrgsResponse) 4700 4701 def profile(self, user: str, input: UserProfileInput) -> User: 4702 """ 4703 Update the current user's profile 4704 Updates one or more profile fields for the authenticated user. All 4705 fields are optional; omit any you do not want to change. 4706 When `profile_picture` is supplied, the image is uploaded and replaces 4707 the existing picture. The previous picture is deleted after the new one 4708 is stored. Image upload failures return 422 without modifying other 4709 profile fields. 4710 4711 Args: 4712 user: User ID (`usr_...`) or `"me"` for the authenticated user. 4713 input: Request body. 4714 input.alias: Short display alias shown in place of the full name in compact UI contexts. 4715 input.clear_full_name: Set to true to clear the optional display name. Cannot be combined with full_name. 4716 input.clear_profile_picture: Set to true to remove the current profile picture. Cannot be combined with profile_picture. 4717 input.full_name: Updated display name for the user. 4718 input.metadata: Arbitrary key-value metadata to associate with the user. Existing keys are merged; pass `null` for a key to remove it. 4719 input.profile_picture: New profile picture to upload as a base64-encoded image. Replaces any existing picture. 4720 4721 Returns: 4722 The user object with updated profile fields. 4723 """ 4724 return self._http.request( 4725 f"/api/v1/users/{user}/profile", 4726 method="PUT", 4727 body=input, 4728 response_type=User, 4729 ) 4730 4731 def task_epics( 4732 self, 4733 user: str, 4734 *, 4735 team: str | None = None, 4736 org: str | None = None, 4737 source_scope: str | None = None, 4738 source_type: str | None = None, 4739 source_id: str | None = None, 4740 top_priority: int | None = None, 4741 include_closed: bool | None = None, 4742 limit: int | None = None, 4743 after_cursor: str | None = None, 4744 ) -> UserTaskEpicsResponse: 4745 """ 4746 List an owner's epic summaries 4747 Groups tasks by their exact epic label, ordered by label. Closed tasks include cancelled tasks, but cancelled prerequisites still block. Source filters select the tasks summarized; blockers outside that selection still affect readiness. Root ranking is capped per epic and root_blockers_partial is true when that graph is truncated. No epic entity is created. 4748 4749 Args: 4750 source_scope: Exact source scope; supply all three source fields. 4751 source_type: Exact source type. 4752 source_id: Exact source ID. 4753 top_priority: Exact highest open priority, from 0 to 4. 4754 include_closed: Include epics with no non-closed tasks; defaults to false. 4755 limit: Maximum epics; defaults to 50, capped at 100. 4756 after_cursor: Opaque forward cursor from the preceding page. 4757 4758 Returns: 4759 Successful response 4760 """ 4761 query: dict[str, object] = {} 4762 if team is not None: 4763 query["team"] = team 4764 if org is not None: 4765 query["org"] = org 4766 if source_scope is not None: 4767 query["source_scope"] = source_scope 4768 if source_type is not None: 4769 query["source_type"] = source_type 4770 if source_id is not None: 4771 query["source_id"] = source_id 4772 if top_priority is not None: 4773 query["top_priority"] = top_priority 4774 if include_closed is not None: 4775 query["include_closed"] = include_closed 4776 if limit is not None: 4777 query["limit"] = limit 4778 if after_cursor is not None: 4779 query["after_cursor"] = after_cursor 4780 return self._http.request( 4781 f"/api/v1/users/{user}/task_epics", 4782 query=query, 4783 response_type=UserTaskEpicsResponse, 4784 )
class
UserSshKeyCreateInput(typing.TypedDict):
22class UserSshKeyCreateInput(TypedDict): 23 "Register an SSH public key" 24 25 label: str 26 "A label such as `Work laptop`." 27 public_key: str 28 "One `ssh-ed25519 <base64>` public key without options or a comment."
Register an SSH public key
class
UserTaskCreateInputTask(typing.TypedDict):
31class UserTaskCreateInputTask(TypedDict, total=False): 32 description: str | None 33 "Optional long-form description or notes for the task. Supports plain text." 34 due_date: datetime | None 35 "Date and time by which the task should be completed (ISO 8601). Omit to create the task without a due date." 36 epic: str | None 37 "Optional free-form grouping label." 38 id: str | None 39 "Optional caller-generated task public ID (`tsk_...`). Persist it before creating a task when creation must survive a lost response. An existing ID returns 409 without modifying the task; read the task by ID to reconcile. Omit for a server-generated ID." 40 links: dict[str, Any] | None 41 "Arbitrary key-value map of named URLs or references associated with the task (e.g. external ticket links)." 42 metadata: dict[str, Any] | None 43 "Arbitrary key-value map for storing application-specific data alongside the task. Omit to create the task with no metadata." 44 name: Required[str] 45 "Human-readable title for the task." 46 owner_agent: str | None 47 "ID of the agent to assign as owner (`agi_...`). Mutually exclusive with `owner_user`; omit to leave the task unassigned." 48 owner_user: str | None 49 "ID of the user to assign as owner (`usr_...`). Mutually exclusive with `owner_agent`; omit to leave the task unassigned." 50 parent: str | None 51 "Create this task as a subtask of an existing top-level task (`tsk_...`). Subtasks nest exactly one level." 52 priority: int | None 53 "Priority level from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when omitted." 54 project_id: str | None 55 "Optional project ID (`prj_...`). Pass null to clear it." 56 source_id: str | None 57 "Source object identity (for example `ArchAstro/firstlanding`)." 58 source_scope: str | None 59 "Container of the work this task is about (for example `github.com`). Must be supplied with `source_type` and `source_id`." 60 source_type: str | None 61 "Kind of source object (for example `repository`)." 62 status: str | None 63 'Initial status for the task. One of `"open"`, `"in_progress"`, `"in_review"`, `"paused"`, `"failed"`, `"superseding"`, `"done"`, or `"cancelled"`. Defaults to `"open"` when omitted.' 64 tags: list[str] | None 65 "Labels for grouping and filtering (max 20, each up to 40 characters). Stored canonically: lowercase, trimmed, de-duplicated." 66 target_binary: str | None 67 "Binary that must run this work, as a lowercase identifier of 1-64 characters (letters, digits, `.`, `_`, `-`; for example `my-cli`). Must be supplied with `target_version`." 68 target_version: str | None 69 "Minimum semantic version of `target_binary` that can run this work (`MAJOR.MINOR.PATCH` with optional prerelease and build, no leading `v`). Must be supplied with `target_binary`." 70 thread: str | None 71 "Bind the task to a thread (`thr_...`) owned by the same team or user as the task. A bound task appears in that thread's task scope, exactly like a task filed from inside the conversation. Omit for a task not tied to a conversation."
due_date: datetime.datetime | None
Date and time by which the task should be completed (ISO 8601). Omit to create the task without a due date.
id: str | None
Optional caller-generated task public ID (tsk_...). Persist it before creating a task when creation must survive a lost response. An existing ID returns 409 without modifying the task; read the task by ID to reconcile. Omit for a server-generated ID.
links: dict[str, typing.Any] | None
Arbitrary key-value map of named URLs or references associated with the task (e.g. external ticket links).
metadata: dict[str, typing.Any] | None
Arbitrary key-value map for storing application-specific data alongside the task. Omit to create the task with no metadata.
owner_agent: str | None
ID of the agent to assign as owner (agi_...). Mutually exclusive with owner_user; omit to leave the task unassigned.
owner_user: str | None
ID of the user to assign as owner (usr_...). Mutually exclusive with owner_agent; omit to leave the task unassigned.
parent: str | None
Create this task as a subtask of an existing top-level task (tsk_...). Subtasks nest exactly one level.
priority: int | None
Priority level from 0 (highest) to 4 (lowest). Defaults to 2 (medium) when omitted.
source_scope: str | None
Container of the work this task is about (for example github.com). Must be supplied with source_type and source_id.
status: str | None
Initial status for the task. One of "open", "in_progress", "in_review", "paused", "failed", "superseding", "done", or "cancelled". Defaults to "open" when omitted.
target_binary: str | None
Binary that must run this work, as a lowercase identifier of 1-64 characters (letters, digits, ., _, -; for example my-cli). Must be supplied with target_version.
target_version: str | None
Minimum semantic version of target_binary that can run this work (MAJOR.MINOR.PATCH with optional prerelease and build, no leading v). Must be supplied with target_binary.
class
UserTaskCreateInput(typing.TypedDict):
74class UserTaskCreateInput(TypedDict, total=False): 75 "Create a task for an owner" 76 77 agent: str | None 78 "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." 79 org: str | None 80 "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." 81 task: Required[UserTaskCreateInputTask] 82 "Attributes for the task to create. `name` is required; all other fields are optional." 83 team: str | None 84 "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
UserTaskBySourceInput(typing.TypedDict):
87class UserTaskBySourceInput(TypedDict, total=False): 88 "Find or create a task by source" 89 90 agent: str | None 91 "Explicit acting agent for privileged callers." 92 description: str | None 93 "Initial task description." 94 epic: str | None 95 "Initial epic grouping." 96 name: Required[str] 97 "Initial task name." 98 org: str | None 99 "Explicit organization for privileged callers." 100 source_id: Required[str] 101 "Source identity, for example owner/repo#123." 102 source_scope: Required[str] 103 "Source scope, for example github." 104 source_type: Required[str] 105 "Source type, for example pull_request." 106 status: str | None 107 "Initial task status." 108 team: str | None 109 "Team owner."
Find or create a task by source
class
UserThreadCreateInputThreadMembersItem(typing.TypedDict):
class
UserThreadCreateInputThreadProfilePicture(typing.TypedDict):
119class UserThreadCreateInputThreadProfilePicture(TypedDict, total=False): 120 data: str | None 121 "Base64-encoded image bytes." 122 filename: str | None 123 "Original filename of the uploaded image, used for display and content-type inference." 124 mime_type: str | None 125 'MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`.'
class
UserThreadCreateInputThreadSettings(typing.TypedDict):
128class UserThreadCreateInputThreadSettings(TypedDict, total=False): 129 agent_enabled: bool | None 130 "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):
133class UserThreadCreateInputThread(TypedDict, total=False): 134 create_legacy_agent: bool | None 135 "When `true`, provisions a legacy chat agent alongside the thread. Only needed for integrations that depend on the pre-v2 agent model." 136 description: str | None 137 "Optional longer description of the thread's purpose. `null` if not provided." 138 is_unlisted: bool | None 139 "When `true`, the thread is hidden from the default thread list and accessible only by direct link or ID." 140 key: str | None 141 "Client-assigned unique key for idempotent creation or later lookup. Must be unique within the owning organization." 142 kind: Literal["personal", "feed"] | None 143 "Optional behavioral subtype. `personal` is accepted only for a user-owned thread and limits membership to that user and agents currently owned by them. `feed` is accepted for any owner and renders the thread as a post feed: message lists return top-level posts with their newest replies inline, and agent responses attach to the root post. Mirror kinds remain server-derived and cannot be selected by callers." 144 members: list[UserThreadCreateInputThreadMembersItem] | None 145 "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." 146 metadata: dict[str, Any] | None 147 "Arbitrary key-value pairs stored alongside the thread. Values must be strings or numbers." 148 muted: bool | None 149 "When `true`, push and in-app notifications for this thread are suppressed for the creating user." 150 org_id: str | None 151 "ID of the organization to create the thread under. Defaults to the authenticated user's primary organization when omitted." 152 profile_picture: UserThreadCreateInputThreadProfilePicture | None 153 "Optional profile image for the thread, provided as a base64-encoded payload." 154 settings: UserThreadCreateInputThreadSettings | None 155 "Configuration overrides for the thread, such as AI model selection and context window settings." 156 slug: str | None 157 "Optional URL-safe identifier. Derived from the title when omitted and unique within the thread owner." 158 title: str | None 159 "Display name for the thread. `null` if omitted, which causes the thread to be untitled." 160 visibility: Literal["team", "restricted", "private", "org"] | None 161 "Thread visibility. A team-owned thread with members must explicitly use `restricted` or `private`. User- and agent-owned threads with members default to `private` and reject every other value. `org` is only valid on an organization-owned thread with no team, user, or agent owner."
create_legacy_agent: bool | None
When true, provisions a legacy chat agent alongside the thread. Only needed for integrations that depend on the pre-v2 agent model.
is_unlisted: bool | None
When true, the thread is hidden from the default thread list and accessible only by direct link or ID.
key: str | None
Client-assigned unique key for idempotent creation or later lookup. Must be unique within the owning organization.
kind: Optional[Literal['personal', 'feed']]
Optional behavioral subtype. personal is accepted only for a user-owned thread and limits membership to that user and agents currently owned by them. feed is accepted for any owner and renders the thread as a post feed: message lists return top-level posts with their newest replies inline, and agent responses attach to the root post. Mirror kinds remain server-derived and cannot be selected by callers.
members: list[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.
title: str | None
Display name for the thread. null if omitted, which causes the thread to be untitled.
visibility: Optional[Literal['team', 'restricted', 'private', 'org']]
Thread visibility. A team-owned thread with members must explicitly use restricted or private. User- and agent-owned threads with members default to private and reject every other value. org is only valid on an organization-owned thread with no team, user, or agent owner.
class
UserThreadCreateInput(typing.TypedDict):
164class UserThreadCreateInput(TypedDict, total=False): 165 "Create a thread for a user" 166 167 skip_welcome_message: bool | None 168 "When `true`, suppresses the automatic welcome message that is otherwise sent into the thread on creation. Defaults to `false`." 169 thread: Required[UserThreadCreateInputThread] 170 "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):
173class TokenCreateInput(TypedDict, total=False): 174 "Create a personal access token" 175 176 expires_in_days: int | None 177 "Lifetime in days. One of `7`, `30`, `60`, `90`, or `365`. Defaults to `30`." 178 name: str | None 179 'Human-readable label for the token (e.g. `"Codex MCP"`). Stored as metadata only.' 180 scopes: list[str] | None 181 "Optional OAuth scopes to stamp on the token. Omit for `full_access`."
Create a personal access token
class
UserInvitesInputInvite(typing.TypedDict):
184class UserInvitesInputInvite(TypedDict, total=False): 185 metadata: dict[str, Any] | None 186 "Arbitrary key-value metadata to attach to the invite. Returned as-is on the resulting invite object." 187 persona_id: str | None 188 "ID of the persona to associate with this invite (`per_...`). `null` if the invite is not bound to a persona." 189 thread_id: str | None 190 "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):
193class UserInvitesInput(TypedDict): 194 "Create a user invite" 195 196 invite: UserInvitesInputInvite 197 "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):
200class UserProfileInputProfilePicture(TypedDict, total=False): 201 data: str | None 202 "Base64-encoded binary content of the image file." 203 filename: str | None 204 "Original filename of the image, used for storage metadata." 205 mime_type: str | None 206 'MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`.'
class
UserProfileInput(typing.TypedDict):
209class UserProfileInput(TypedDict, total=False): 210 "Update the current user's profile" 211 212 alias: str | None 213 "Short display alias shown in place of the full name in compact UI contexts." 214 clear_full_name: bool | None 215 "Set to true to clear the optional display name. Cannot be combined with full_name." 216 clear_profile_picture: bool | None 217 "Set to true to remove the current profile picture. Cannot be combined with profile_picture." 218 full_name: str | None 219 "Updated display name for the user." 220 metadata: dict[str, Any] | None 221 "Arbitrary key-value metadata to associate with the user. Existing keys are merged; pass `null` for a key to remove it." 222 profile_picture: UserProfileInputProfilePicture | None 223 "New profile picture to upload as a base64-encoded image. Replaces any existing picture."
Update the current user's profile
clear_full_name: bool | None
Set to true to clear the optional display name. Cannot be combined with full_name.
clear_profile_picture: bool | None
Set to true to remove the current profile picture. Cannot be combined with profile_picture.
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
IntegrationAccessTokenResponse(pydantic.main.BaseModel):
226class IntegrationAccessTokenResponse(BaseModel): 227 """ 228 Successful response 229 """ 230 231 access_token: str = Field(..., description="GitHub access token. Treat this value as a secret.") 232 expires_at: datetime | None = Field( 233 default=None, description="Access-token expiry, or null for non-expiring tokens." 234 ) 235 integration: str = Field(..., description="Integration ID (`int_...`).") 236 provider: str = Field(..., description="Always `github`.") 237 scopes: list[str] = Field(..., description="Recorded GitHub OAuth scopes.") 238 token_kind: str = Field( 239 ..., description="Credential authority model: `oauth` or `github_app_user`." 240 ) 241 workspace_key: str | None = Field( 242 default=None, description="GitHub login associated with the credential." 243 )
Successful response
class
UserSshKeyListResponseDataItem(pydantic.main.BaseModel):
246class UserSshKeyListResponseDataItem(BaseModel): 247 algorithm: str = Field(..., description="SSH algorithm. V1 accepts `ssh-ed25519`.") 248 created_at: datetime = Field(..., description="Registration time.") 249 fingerprint: str = Field(..., description="OpenSSH SHA-256 fingerprint.") 250 id: str = Field(..., description="Registered SSH key ID (`ssk_...`).") 251 label: str = Field(..., description="User-visible label for the key.") 252 revoked_at: datetime | None = Field( 253 default=None, description="Revocation time, or null while active." 254 )
!!! 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
UserSshKeyListResponse(pydantic.main.BaseModel):
257class UserSshKeyListResponse(BaseModel): 258 """ 259 Successful response 260 """ 261 262 after_cursor: str | None = None 263 before_cursor: str | None = None 264 data: list[UserSshKeyListResponseDataItem] 265 has_more: bool
Successful response
class
UserTaskListResponseDataItemCreatedByActorProfilePicture(pydantic.main.BaseModel):
268class UserTaskListResponseDataItemCreatedByActorProfilePicture(BaseModel): 269 file: str | None = Field( 270 default=None, 271 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 272 ) 273 height: int | None = Field( 274 default=None, description="Height of the image in pixels. `null` if not known." 275 ) 276 media: str | None = Field( 277 default=None, 278 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 279 ) 280 mime_type: str | None = Field( 281 default=None, 282 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 283 ) 284 refresh_url: str | None = Field( 285 default=None, 286 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.", 287 ) 288 url: str | None = Field( 289 default=None, 290 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.", 291 ) 292 width: int | None = Field( 293 default=None, description="Width of the image in pixels. `null` if not known." 294 )
!!! 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):
297class UserTaskListResponseDataItemCreatedByActor(BaseModel): 298 alias: str | None = Field( 299 default=None, 300 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 301 ) 302 id: str | None = Field( 303 default=None, 304 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 305 ) 306 name: str | None = Field( 307 default=None, 308 description="Display name of the actor shown in the UI. `null` if no name is set.", 309 ) 310 profile_picture: UserTaskListResponseDataItemCreatedByActorProfilePicture | None = Field( 311 default=None, 312 description="Profile picture for the actor. `null` if the actor has no profile picture.", 313 )
!!! 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):
316class UserTaskListResponseDataItemCurrentLease(BaseModel): 317 expires_at: datetime = Field( 318 ..., description="Server-calculated lease expiry in ISO 8601 format." 319 ) 320 harness: str = Field(..., description="Bounded harness identifier for the coding session.") 321 session_name: str = Field( 322 ..., description="Display name supplied by the coding session that holds the lease." 323 )
!!! 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):
326class UserTaskListResponseDataItemOwnerActorProfilePicture(BaseModel): 327 file: str | None = Field( 328 default=None, 329 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 330 ) 331 height: int | None = Field( 332 default=None, description="Height of the image in pixels. `null` if not known." 333 ) 334 media: str | None = Field( 335 default=None, 336 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 337 ) 338 mime_type: str | None = Field( 339 default=None, 340 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 341 ) 342 refresh_url: str | None = Field( 343 default=None, 344 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.", 345 ) 346 url: str | None = Field( 347 default=None, 348 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.", 349 ) 350 width: int | None = Field( 351 default=None, description="Width of the image in pixels. `null` if not known." 352 )
!!! 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):
355class UserTaskListResponseDataItemOwnerActor(BaseModel): 356 alias: str | None = Field( 357 default=None, 358 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 359 ) 360 id: str | None = Field( 361 default=None, 362 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 363 ) 364 name: str | None = Field( 365 default=None, 366 description="Display name of the actor shown in the UI. `null` if no name is set.", 367 ) 368 profile_picture: UserTaskListResponseDataItemOwnerActorProfilePicture | None = Field( 369 default=None, 370 description="Profile picture for the actor. `null` if the actor has no profile picture.", 371 )
!!! 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):
374class UserTaskListResponseDataItem(BaseModel): 375 agent: str | None = Field( 376 default=None, 377 description="ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", 378 ) 379 aggregate_version: int | None = Field( 380 default=None, 381 description="Event-stream version for optimistic update fencing. Pass this value as `expected_version` on an update to reject concurrent writes.", 382 ) 383 blocked_by_count: int | None = Field( 384 default=None, 385 description="Number of readable tasks marked as blocking this task, whether or not they are done (see `GET /tasks/{task}/blockers`). Computed on list/show reads; create/update responses may lag one read behind.", 386 ) 387 closed_at: datetime | None = Field( 388 default=None, 389 description="When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", 390 ) 391 comments_count: int | None = Field( 392 default=None, description="Total number of comments posted on this task." 393 ) 394 created_at: datetime | None = Field( 395 default=None, description="When the task was created (ISO 8601)." 396 ) 397 created_by_actor: UserTaskListResponseDataItemCreatedByActor | None = Field( 398 default=None, 399 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).", 400 ) 401 created_by_agent: str | None = Field( 402 default=None, 403 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.", 404 ) 405 created_by_user: str | None = Field( 406 default=None, 407 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.", 408 ) 409 current_lease: UserTaskListResponseDataItemCurrentLease | None = Field( 410 default=None, 411 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.", 412 ) 413 description: str | None = Field( 414 default=None, 415 description="Long-form description or notes for the task. `null` if no description has been provided.", 416 ) 417 due_date: datetime | None = Field( 418 default=None, 419 description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", 420 ) 421 epic: str | None = Field( 422 default=None, 423 description="Free-form grouping label. `null` when the task is not in an epic.", 424 ) 425 id: str = Field(..., description="Task ID (`tsk_...`).") 426 is_blocked: bool | None = Field( 427 default=None, 428 description="`true` while at least one blocking task is not yet done. Informational only - a blocked task can still change status - and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on reads, including mutation responses.", 429 ) 430 is_stalled: bool | None = Field( 431 default=None, 432 description="True exactly when status is in_progress and the task has no lease or its lease expiry is in the past. Derived at read time from status and lease expiry, including on unannotated reads.", 433 ) 434 links: dict[str, Any] | None = Field( 435 default=None, 436 description="Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.", 437 ) 438 metadata: dict[str, Any] | None = Field( 439 default=None, 440 description="Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.", 441 ) 442 name: str = Field(..., description="Human-readable title of the task.") 443 org: str | None = Field( 444 default=None, 445 description="ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", 446 ) 447 owner_actor: UserTaskListResponseDataItemOwnerActor | None = Field( 448 default=None, 449 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).", 450 ) 451 owner_agent: str | None = Field( 452 default=None, 453 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.", 454 ) 455 owner_user: str | None = Field( 456 default=None, 457 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.", 458 ) 459 parent: str | None = Field( 460 default=None, 461 description="ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks or when the parent is not readable. Subtasks nest exactly one level.", 462 ) 463 priority: int | None = Field( 464 default=None, 465 description="Priority level of the task from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when not explicitly set.", 466 ) 467 project_id: str | None = Field( 468 default=None, 469 description="Optional project ID (`prj_...`). Membership does not change task visibility.", 470 ) 471 sandbox: str | None = Field( 472 default=None, 473 description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", 474 ) 475 source_id: str | None = Field( 476 default=None, 477 description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", 478 ) 479 source_scope: str | None = Field( 480 default=None, 481 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`.", 482 ) 483 source_type: str | None = Field( 484 default=None, 485 description="Kind of source object (for example `repository`). `null` when the task has no source.", 486 ) 487 stalled_since: datetime | None = Field( 488 default=None, 489 description="Lease expiry for a stalled task, or its last update when no lease expiry exists. Null when not stalled.", 490 ) 491 status: str = Field( 492 ..., 493 description='Current status of the task. One of `"open"`, `"in_progress"`, `"in_review"`, `"paused"`, `"failed"`, `"superseding"`, `"done"`, or `"cancelled"`.', 494 ) 495 subtasks_count: int | None = Field( 496 default=None, 497 description="Number of readable subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.", 498 ) 499 tags: list[str] | None = Field( 500 default=None, 501 description="Labels for grouping and filtering, stored lowercase and de-duplicated. Empty array when untagged.", 502 ) 503 target_binary: str | None = Field( 504 default=None, 505 description="Binary that must run this work (for example `my-cli`). A worker should take the task only when its own `target_binary` build is at least `target_version`. `null` when the task has no target. Set together with `target_version`.", 506 ) 507 target_version: str | None = Field( 508 default=None, 509 description="Minimum semantic version of `target_binary` that can run this work (for example `0.48.9`), in canonical `MAJOR.MINOR.PATCH[-prerelease][+build]` form. `null` when the task has no target.", 510 ) 511 team: str | None = Field( 512 default=None, 513 description="ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", 514 ) 515 thread: str | None = Field( 516 default=None, 517 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.", 518 ) 519 updated_at: datetime | None = Field( 520 default=None, description="When the task was last modified (ISO 8601)." 521 ) 522 user: str | None = Field( 523 default=None, 524 description="ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", 525 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
agent: str | None =
None
ID of the agent that owns this task (agi_...). null if the task is scoped to a team or user.
aggregate_version: int | None =
None
Event-stream version for optimistic update fencing. Pass this value as expected_version on an update to reject concurrent writes.
blocked_by_count: int | None =
None
Number of readable tasks marked as blocking this task, whether or not they are done (see GET /tasks/{task}/blockers). Computed on list/show reads; create/update responses may lag one read behind.
closed_at: datetime.datetime | None =
None
When the task was marked as done or otherwise closed (ISO 8601). null if the task is still open.
created_by_agent: str | None =
None
ID of the agent that created this task (agi_...). null if the task was created by a human user, or if the creating agent was later deleted.
created_by_user: str | None =
None
ID of the user who created this task (usr_...). null if the task was created by an agent, or if creator provenance was cleared after the creator was deleted.
Viewer-safe live coding-session lease summary. null when the task is unleased or the projected lease has expired. Fencing identifiers are never included.
description: str | None =
None
Long-form description or notes for the task. null if no description has been provided.
due_date: datetime.datetime | None =
None
Date and time by which the task should be completed (ISO 8601). null if no due date is set.
is_blocked: bool | None =
None
true while at least one blocking task is not yet done. Informational only - a blocked task can still change status - and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on reads, including mutation responses.
is_stalled: bool | None =
None
True exactly when status is in_progress and the task has no lease or its lease expiry is in the past. Derived at read time from status and lease expiry, including on unannotated reads.
links: dict[str, typing.Any] | None =
None
Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.
metadata: dict[str, typing.Any] | None =
None
Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.
org: str | None =
None
ID of the organization this task belongs to (org_...). null for tasks outside an org context.
owner_agent: str | None =
None
ID of the agent assigned as owner (agi_...). null if the owner is a human user, the task is unassigned, or the assigned agent was deleted.
owner_user: str | None =
None
ID of the user assigned as owner (usr_...). null if the owner is an agent, the task is unassigned, or the assigned agent was deleted.
parent: str | None =
None
ID of the parent task when this task is a subtask (tsk_...). null for top-level tasks or when the parent is not readable. Subtasks nest exactly one level.
priority: int | None =
None
Priority level of the task from 0 (highest) to 4 (lowest). Defaults to 2 (medium) when not explicitly set.
project_id: str | None =
None
Optional project ID (prj_...). Membership does not change task visibility.
sandbox: str | None =
None
ID of the developer sandbox this task is scoped to (dsb_...). null for tasks outside a sandbox environment.
source_id: str | None =
None
Source object identity (for example ArchAstro/firstlanding). null when the task has no source.
source_scope: str | None =
None
Container of the work this task is about (for example github.com). null when the task has no source. Set together with source_type and source_id.
source_type: str | None =
None
Kind of source object (for example repository). null when the task has no source.
stalled_since: datetime.datetime | None =
None
Lease expiry for a stalled task, or its last update when no lease expiry exists. Null when not stalled.
status: str =
PydanticUndefined
Current status of the task. One of "open", "in_progress", "in_review", "paused", "failed", "superseding", "done", or "cancelled".
subtasks_count: int | None =
None
Number of readable subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.
target_binary: str | None =
None
Binary that must run this work (for example my-cli). A worker should take the task only when its own target_binary build is at least target_version. null when the task has no target. Set together with target_version.
target_version: str | None =
None
Minimum semantic version of target_binary that can run this work (for example 0.48.9), in canonical MAJOR.MINOR.PATCH[-prerelease][+build] form. null when the task has no target.
team: str | None =
None
ID of the team that owns this task (tem_...). null if the task is not scoped to a team.
class
UserTaskListResponse(pydantic.main.BaseModel):
528class UserTaskListResponse(BaseModel): 529 """ 530 Successful response 531 """ 532 533 after_cursor: str | None = None 534 before_cursor: str | None = None 535 data: list[UserTaskListResponseDataItem] = Field( 536 ..., description="Array of task objects matching the requested filters." 537 ) 538 has_more: bool
Successful response
class
UserTaskBlockerCyclesResponseDataItemTasksItemCreatedByActorProfilePicture(pydantic.main.BaseModel):
541class UserTaskBlockerCyclesResponseDataItemTasksItemCreatedByActorProfilePicture(BaseModel): 542 file: str | None = Field( 543 default=None, 544 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 545 ) 546 height: int | None = Field( 547 default=None, description="Height of the image in pixels. `null` if not known." 548 ) 549 media: str | None = Field( 550 default=None, 551 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 552 ) 553 mime_type: str | None = Field( 554 default=None, 555 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 556 ) 557 refresh_url: str | None = Field( 558 default=None, 559 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.", 560 ) 561 url: str | None = Field( 562 default=None, 563 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.", 564 ) 565 width: int | None = Field( 566 default=None, description="Width of the image in pixels. `null` if not known." 567 )
!!! 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):
570class UserTaskBlockerCyclesResponseDataItemTasksItemCreatedByActor(BaseModel): 571 alias: str | None = Field( 572 default=None, 573 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 574 ) 575 id: str | None = Field( 576 default=None, 577 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 578 ) 579 name: str | None = Field( 580 default=None, 581 description="Display name of the actor shown in the UI. `null` if no name is set.", 582 ) 583 profile_picture: ( 584 UserTaskBlockerCyclesResponseDataItemTasksItemCreatedByActorProfilePicture | None 585 ) = Field( 586 default=None, 587 description="Profile picture for the actor. `null` if the actor has no profile picture.", 588 )
!!! 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):
591class UserTaskBlockerCyclesResponseDataItemTasksItemCurrentLease(BaseModel): 592 expires_at: datetime = Field( 593 ..., description="Server-calculated lease expiry in ISO 8601 format." 594 ) 595 harness: str = Field(..., description="Bounded harness identifier for the coding session.") 596 session_name: str = Field( 597 ..., description="Display name supplied by the coding session that holds the lease." 598 )
!!! 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):
601class UserTaskBlockerCyclesResponseDataItemTasksItemOwnerActorProfilePicture(BaseModel): 602 file: str | None = Field( 603 default=None, 604 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 605 ) 606 height: int | None = Field( 607 default=None, description="Height of the image in pixels. `null` if not known." 608 ) 609 media: str | None = Field( 610 default=None, 611 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 612 ) 613 mime_type: str | None = Field( 614 default=None, 615 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 616 ) 617 refresh_url: str | None = Field( 618 default=None, 619 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.", 620 ) 621 url: str | None = Field( 622 default=None, 623 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.", 624 ) 625 width: int | None = Field( 626 default=None, description="Width of the image in pixels. `null` if not known." 627 )
!!! 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):
630class UserTaskBlockerCyclesResponseDataItemTasksItemOwnerActor(BaseModel): 631 alias: str | None = Field( 632 default=None, 633 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 634 ) 635 id: str | None = Field( 636 default=None, 637 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 638 ) 639 name: str | None = Field( 640 default=None, 641 description="Display name of the actor shown in the UI. `null` if no name is set.", 642 ) 643 profile_picture: ( 644 UserTaskBlockerCyclesResponseDataItemTasksItemOwnerActorProfilePicture | None 645 ) = Field( 646 default=None, 647 description="Profile picture for the actor. `null` if the actor has no profile picture.", 648 )
!!! 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):
651class UserTaskBlockerCyclesResponseDataItemTasksItem(BaseModel): 652 agent: str | None = Field( 653 default=None, 654 description="ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", 655 ) 656 aggregate_version: int | None = Field( 657 default=None, 658 description="Event-stream version for optimistic update fencing. Pass this value as `expected_version` on an update to reject concurrent writes.", 659 ) 660 blocked_by_count: int | None = Field( 661 default=None, 662 description="Number of readable tasks marked as blocking this task, whether or not they are done (see `GET /tasks/{task}/blockers`). Computed on list/show reads; create/update responses may lag one read behind.", 663 ) 664 closed_at: datetime | None = Field( 665 default=None, 666 description="When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", 667 ) 668 comments_count: int | None = Field( 669 default=None, description="Total number of comments posted on this task." 670 ) 671 created_at: datetime | None = Field( 672 default=None, description="When the task was created (ISO 8601)." 673 ) 674 created_by_actor: UserTaskBlockerCyclesResponseDataItemTasksItemCreatedByActor | None = Field( 675 default=None, 676 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).", 677 ) 678 created_by_agent: str | None = Field( 679 default=None, 680 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.", 681 ) 682 created_by_user: str | None = Field( 683 default=None, 684 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.", 685 ) 686 current_lease: UserTaskBlockerCyclesResponseDataItemTasksItemCurrentLease | None = Field( 687 default=None, 688 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.", 689 ) 690 description: str | None = Field( 691 default=None, 692 description="Long-form description or notes for the task. `null` if no description has been provided.", 693 ) 694 due_date: datetime | None = Field( 695 default=None, 696 description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", 697 ) 698 epic: str | None = Field( 699 default=None, 700 description="Free-form grouping label. `null` when the task is not in an epic.", 701 ) 702 id: str = Field(..., description="Task ID (`tsk_...`).") 703 is_blocked: bool | None = Field( 704 default=None, 705 description="`true` while at least one blocking task is not yet done. Informational only - a blocked task can still change status - and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on reads, including mutation responses.", 706 ) 707 is_stalled: bool | None = Field( 708 default=None, 709 description="True exactly when status is in_progress and the task has no lease or its lease expiry is in the past. Derived at read time from status and lease expiry, including on unannotated reads.", 710 ) 711 links: dict[str, Any] | None = Field( 712 default=None, 713 description="Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.", 714 ) 715 metadata: dict[str, Any] | None = Field( 716 default=None, 717 description="Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.", 718 ) 719 name: str = Field(..., description="Human-readable title of the task.") 720 org: str | None = Field( 721 default=None, 722 description="ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", 723 ) 724 owner_actor: UserTaskBlockerCyclesResponseDataItemTasksItemOwnerActor | None = Field( 725 default=None, 726 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).", 727 ) 728 owner_agent: str | None = Field( 729 default=None, 730 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.", 731 ) 732 owner_user: str | None = Field( 733 default=None, 734 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.", 735 ) 736 parent: str | None = Field( 737 default=None, 738 description="ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks or when the parent is not readable. Subtasks nest exactly one level.", 739 ) 740 priority: int | None = Field( 741 default=None, 742 description="Priority level of the task from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when not explicitly set.", 743 ) 744 project_id: str | None = Field( 745 default=None, 746 description="Optional project ID (`prj_...`). Membership does not change task visibility.", 747 ) 748 sandbox: str | None = Field( 749 default=None, 750 description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", 751 ) 752 source_id: str | None = Field( 753 default=None, 754 description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", 755 ) 756 source_scope: str | None = Field( 757 default=None, 758 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`.", 759 ) 760 source_type: str | None = Field( 761 default=None, 762 description="Kind of source object (for example `repository`). `null` when the task has no source.", 763 ) 764 stalled_since: datetime | None = Field( 765 default=None, 766 description="Lease expiry for a stalled task, or its last update when no lease expiry exists. Null when not stalled.", 767 ) 768 status: str = Field( 769 ..., 770 description='Current status of the task. One of `"open"`, `"in_progress"`, `"in_review"`, `"paused"`, `"failed"`, `"superseding"`, `"done"`, or `"cancelled"`.', 771 ) 772 subtasks_count: int | None = Field( 773 default=None, 774 description="Number of readable subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.", 775 ) 776 tags: list[str] | None = Field( 777 default=None, 778 description="Labels for grouping and filtering, stored lowercase and de-duplicated. Empty array when untagged.", 779 ) 780 target_binary: str | None = Field( 781 default=None, 782 description="Binary that must run this work (for example `my-cli`). A worker should take the task only when its own `target_binary` build is at least `target_version`. `null` when the task has no target. Set together with `target_version`.", 783 ) 784 target_version: str | None = Field( 785 default=None, 786 description="Minimum semantic version of `target_binary` that can run this work (for example `0.48.9`), in canonical `MAJOR.MINOR.PATCH[-prerelease][+build]` form. `null` when the task has no target.", 787 ) 788 team: str | None = Field( 789 default=None, 790 description="ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", 791 ) 792 thread: str | None = Field( 793 default=None, 794 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.", 795 ) 796 updated_at: datetime | None = Field( 797 default=None, description="When the task was last modified (ISO 8601)." 798 ) 799 user: str | None = Field( 800 default=None, 801 description="ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", 802 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
agent: str | None =
None
ID of the agent that owns this task (agi_...). null if the task is scoped to a team or user.
aggregate_version: int | None =
None
Event-stream version for optimistic update fencing. Pass this value as expected_version on an update to reject concurrent writes.
blocked_by_count: int | None =
None
Number of readable tasks marked as blocking this task, whether or not they are done (see GET /tasks/{task}/blockers). Computed on list/show reads; create/update responses may lag one read behind.
closed_at: datetime.datetime | None =
None
When the task was marked as done or otherwise closed (ISO 8601). null if the task is still open.
created_by_agent: str | None =
None
ID of the agent that created this task (agi_...). null if the task was created by a human user, or if the creating agent was later deleted.
created_by_user: str | None =
None
ID of the user who created this task (usr_...). null if the task was created by an agent, or if creator provenance was cleared after the creator was deleted.
Viewer-safe live coding-session lease summary. null when the task is unleased or the projected lease has expired. Fencing identifiers are never included.
description: str | None =
None
Long-form description or notes for the task. null if no description has been provided.
due_date: datetime.datetime | None =
None
Date and time by which the task should be completed (ISO 8601). null if no due date is set.
is_blocked: bool | None =
None
true while at least one blocking task is not yet done. Informational only - a blocked task can still change status - and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on reads, including mutation responses.
is_stalled: bool | None =
None
True exactly when status is in_progress and the task has no lease or its lease expiry is in the past. Derived at read time from status and lease expiry, including on unannotated reads.
links: dict[str, typing.Any] | None =
None
Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.
metadata: dict[str, typing.Any] | None =
None
Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.
org: str | None =
None
ID of the organization this task belongs to (org_...). null for tasks outside an org context.
owner_agent: str | None =
None
ID of the agent assigned as owner (agi_...). null if the owner is a human user, the task is unassigned, or the assigned agent was deleted.
owner_user: str | None =
None
ID of the user assigned as owner (usr_...). null if the owner is an agent, the task is unassigned, or the assigned agent was deleted.
parent: str | None =
None
ID of the parent task when this task is a subtask (tsk_...). null for top-level tasks or when the parent is not readable. Subtasks nest exactly one level.
priority: int | None =
None
Priority level of the task from 0 (highest) to 4 (lowest). Defaults to 2 (medium) when not explicitly set.
project_id: str | None =
None
Optional project ID (prj_...). Membership does not change task visibility.
sandbox: str | None =
None
ID of the developer sandbox this task is scoped to (dsb_...). null for tasks outside a sandbox environment.
source_id: str | None =
None
Source object identity (for example ArchAstro/firstlanding). null when the task has no source.
source_scope: str | None =
None
Container of the work this task is about (for example github.com). null when the task has no source. Set together with source_type and source_id.
source_type: str | None =
None
Kind of source object (for example repository). null when the task has no source.
stalled_since: datetime.datetime | None =
None
Lease expiry for a stalled task, or its last update when no lease expiry exists. Null when not stalled.
status: str =
PydanticUndefined
Current status of the task. One of "open", "in_progress", "in_review", "paused", "failed", "superseding", "done", or "cancelled".
subtasks_count: int | None =
None
Number of readable subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.
target_binary: str | None =
None
Binary that must run this work (for example my-cli). A worker should take the task only when its own target_binary build is at least target_version. null when the task has no target. Set together with target_version.
target_version: str | None =
None
Minimum semantic version of target_binary that can run this work (for example 0.48.9), in canonical MAJOR.MINOR.PATCH[-prerelease][+build] form. null when the task has no target.
team: str | None =
None
ID of the team that owns this task (tem_...). null if the task is not scoped to a team.
class
UserTaskBlockerCyclesResponseDataItem(pydantic.main.BaseModel):
805class UserTaskBlockerCyclesResponseDataItem(BaseModel): 806 tasks: list[UserTaskBlockerCyclesResponseDataItemTasksItem] = Field( 807 ..., description="Every unfinished task in this cyclic blocker component." 808 )
!!! 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):
811class UserTaskBlockerCyclesResponse(BaseModel): 812 """ 813 Successful response 814 """ 815 816 after_cursor: str | None = None 817 before_cursor: str | None = None 818 data: list[UserTaskBlockerCyclesResponseDataItem] 819 has_more: bool
Successful response
class
UserTaskReadyResponseDataItemTaskCreatedByActorProfilePicture(pydantic.main.BaseModel):
822class UserTaskReadyResponseDataItemTaskCreatedByActorProfilePicture(BaseModel): 823 file: str | None = Field( 824 default=None, 825 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 826 ) 827 height: int | None = Field( 828 default=None, description="Height of the image in pixels. `null` if not known." 829 ) 830 media: str | None = Field( 831 default=None, 832 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 833 ) 834 mime_type: str | None = Field( 835 default=None, 836 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 837 ) 838 refresh_url: str | None = Field( 839 default=None, 840 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.", 841 ) 842 url: str | None = Field( 843 default=None, 844 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.", 845 ) 846 width: int | None = Field( 847 default=None, description="Width of the image in pixels. `null` if not known." 848 )
!!! 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):
851class UserTaskReadyResponseDataItemTaskCreatedByActor(BaseModel): 852 alias: str | None = Field( 853 default=None, 854 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 855 ) 856 id: str | None = Field( 857 default=None, 858 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 859 ) 860 name: str | None = Field( 861 default=None, 862 description="Display name of the actor shown in the UI. `null` if no name is set.", 863 ) 864 profile_picture: UserTaskReadyResponseDataItemTaskCreatedByActorProfilePicture | None = Field( 865 default=None, 866 description="Profile picture for the actor. `null` if the actor has no profile picture.", 867 )
!!! 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):
870class UserTaskReadyResponseDataItemTaskCurrentLease(BaseModel): 871 expires_at: datetime = Field( 872 ..., description="Server-calculated lease expiry in ISO 8601 format." 873 ) 874 harness: str = Field(..., description="Bounded harness identifier for the coding session.") 875 session_name: str = Field( 876 ..., description="Display name supplied by the coding session that holds the lease." 877 )
!!! 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):
880class UserTaskReadyResponseDataItemTaskOwnerActorProfilePicture(BaseModel): 881 file: str | None = Field( 882 default=None, 883 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 884 ) 885 height: int | None = Field( 886 default=None, description="Height of the image in pixels. `null` if not known." 887 ) 888 media: str | None = Field( 889 default=None, 890 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 891 ) 892 mime_type: str | None = Field( 893 default=None, 894 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 895 ) 896 refresh_url: str | None = Field( 897 default=None, 898 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.", 899 ) 900 url: str | None = Field( 901 default=None, 902 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.", 903 ) 904 width: int | None = Field( 905 default=None, description="Width of the image in pixels. `null` if not known." 906 )
!!! 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):
909class UserTaskReadyResponseDataItemTaskOwnerActor(BaseModel): 910 alias: str | None = Field( 911 default=None, 912 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 913 ) 914 id: str | None = Field( 915 default=None, 916 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 917 ) 918 name: str | None = Field( 919 default=None, 920 description="Display name of the actor shown in the UI. `null` if no name is set.", 921 ) 922 profile_picture: UserTaskReadyResponseDataItemTaskOwnerActorProfilePicture | None = Field( 923 default=None, 924 description="Profile picture for the actor. `null` if the actor has no profile picture.", 925 )
!!! 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):
928class UserTaskReadyResponseDataItemTask(BaseModel): 929 agent: str | None = Field( 930 default=None, 931 description="ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", 932 ) 933 aggregate_version: int | None = Field( 934 default=None, 935 description="Event-stream version for optimistic update fencing. Pass this value as `expected_version` on an update to reject concurrent writes.", 936 ) 937 blocked_by_count: int | None = Field( 938 default=None, 939 description="Number of readable tasks marked as blocking this task, whether or not they are done (see `GET /tasks/{task}/blockers`). Computed on list/show reads; create/update responses may lag one read behind.", 940 ) 941 closed_at: datetime | None = Field( 942 default=None, 943 description="When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", 944 ) 945 comments_count: int | None = Field( 946 default=None, description="Total number of comments posted on this task." 947 ) 948 created_at: datetime | None = Field( 949 default=None, description="When the task was created (ISO 8601)." 950 ) 951 created_by_actor: UserTaskReadyResponseDataItemTaskCreatedByActor | None = Field( 952 default=None, 953 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).", 954 ) 955 created_by_agent: str | None = Field( 956 default=None, 957 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.", 958 ) 959 created_by_user: str | None = Field( 960 default=None, 961 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.", 962 ) 963 current_lease: UserTaskReadyResponseDataItemTaskCurrentLease | None = Field( 964 default=None, 965 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.", 966 ) 967 description: str | None = Field( 968 default=None, 969 description="Long-form description or notes for the task. `null` if no description has been provided.", 970 ) 971 due_date: datetime | None = Field( 972 default=None, 973 description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", 974 ) 975 epic: str | None = Field( 976 default=None, 977 description="Free-form grouping label. `null` when the task is not in an epic.", 978 ) 979 id: str = Field(..., description="Task ID (`tsk_...`).") 980 is_blocked: bool | None = Field( 981 default=None, 982 description="`true` while at least one blocking task is not yet done. Informational only - a blocked task can still change status - and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on reads, including mutation responses.", 983 ) 984 is_stalled: bool | None = Field( 985 default=None, 986 description="True exactly when status is in_progress and the task has no lease or its lease expiry is in the past. Derived at read time from status and lease expiry, including on unannotated reads.", 987 ) 988 links: dict[str, Any] | None = Field( 989 default=None, 990 description="Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.", 991 ) 992 metadata: dict[str, Any] | None = Field( 993 default=None, 994 description="Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.", 995 ) 996 name: str = Field(..., description="Human-readable title of the task.") 997 org: str | None = Field( 998 default=None, 999 description="ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", 1000 ) 1001 owner_actor: UserTaskReadyResponseDataItemTaskOwnerActor | None = Field( 1002 default=None, 1003 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).", 1004 ) 1005 owner_agent: str | None = Field( 1006 default=None, 1007 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.", 1008 ) 1009 owner_user: str | None = Field( 1010 default=None, 1011 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.", 1012 ) 1013 parent: str | None = Field( 1014 default=None, 1015 description="ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks or when the parent is not readable. Subtasks nest exactly one level.", 1016 ) 1017 priority: int | None = Field( 1018 default=None, 1019 description="Priority level of the task from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when not explicitly set.", 1020 ) 1021 project_id: str | None = Field( 1022 default=None, 1023 description="Optional project ID (`prj_...`). Membership does not change task visibility.", 1024 ) 1025 sandbox: str | None = Field( 1026 default=None, 1027 description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", 1028 ) 1029 source_id: str | None = Field( 1030 default=None, 1031 description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", 1032 ) 1033 source_scope: str | None = Field( 1034 default=None, 1035 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`.", 1036 ) 1037 source_type: str | None = Field( 1038 default=None, 1039 description="Kind of source object (for example `repository`). `null` when the task has no source.", 1040 ) 1041 stalled_since: datetime | None = Field( 1042 default=None, 1043 description="Lease expiry for a stalled task, or its last update when no lease expiry exists. Null when not stalled.", 1044 ) 1045 status: str = Field( 1046 ..., 1047 description='Current status of the task. One of `"open"`, `"in_progress"`, `"in_review"`, `"paused"`, `"failed"`, `"superseding"`, `"done"`, or `"cancelled"`.', 1048 ) 1049 subtasks_count: int | None = Field( 1050 default=None, 1051 description="Number of readable subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.", 1052 ) 1053 tags: list[str] | None = Field( 1054 default=None, 1055 description="Labels for grouping and filtering, stored lowercase and de-duplicated. Empty array when untagged.", 1056 ) 1057 target_binary: str | None = Field( 1058 default=None, 1059 description="Binary that must run this work (for example `my-cli`). A worker should take the task only when its own `target_binary` build is at least `target_version`. `null` when the task has no target. Set together with `target_version`.", 1060 ) 1061 target_version: str | None = Field( 1062 default=None, 1063 description="Minimum semantic version of `target_binary` that can run this work (for example `0.48.9`), in canonical `MAJOR.MINOR.PATCH[-prerelease][+build]` form. `null` when the task has no target.", 1064 ) 1065 team: str | None = Field( 1066 default=None, 1067 description="ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", 1068 ) 1069 thread: str | None = Field( 1070 default=None, 1071 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.", 1072 ) 1073 updated_at: datetime | None = Field( 1074 default=None, description="When the task was last modified (ISO 8601)." 1075 ) 1076 user: str | None = Field( 1077 default=None, 1078 description="ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", 1079 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
agent: str | None =
None
ID of the agent that owns this task (agi_...). null if the task is scoped to a team or user.
aggregate_version: int | None =
None
Event-stream version for optimistic update fencing. Pass this value as expected_version on an update to reject concurrent writes.
blocked_by_count: int | None =
None
Number of readable tasks marked as blocking this task, whether or not they are done (see GET /tasks/{task}/blockers). Computed on list/show reads; create/update responses may lag one read behind.
closed_at: datetime.datetime | None =
None
When the task was marked as done or otherwise closed (ISO 8601). null if the task is still open.
created_by_agent: str | None =
None
ID of the agent that created this task (agi_...). null if the task was created by a human user, or if the creating agent was later deleted.
created_by_user: str | None =
None
ID of the user who created this task (usr_...). null if the task was created by an agent, or if creator provenance was cleared after the creator was deleted.
Viewer-safe live coding-session lease summary. null when the task is unleased or the projected lease has expired. Fencing identifiers are never included.
description: str | None =
None
Long-form description or notes for the task. null if no description has been provided.
due_date: datetime.datetime | None =
None
Date and time by which the task should be completed (ISO 8601). null if no due date is set.
is_blocked: bool | None =
None
true while at least one blocking task is not yet done. Informational only - a blocked task can still change status - and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on reads, including mutation responses.
is_stalled: bool | None =
None
True exactly when status is in_progress and the task has no lease or its lease expiry is in the past. Derived at read time from status and lease expiry, including on unannotated reads.
links: dict[str, typing.Any] | None =
None
Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.
metadata: dict[str, typing.Any] | None =
None
Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.
org: str | None =
None
ID of the organization this task belongs to (org_...). null for tasks outside an org context.
owner_agent: str | None =
None
ID of the agent assigned as owner (agi_...). null if the owner is a human user, the task is unassigned, or the assigned agent was deleted.
owner_user: str | None =
None
ID of the user assigned as owner (usr_...). null if the owner is an agent, the task is unassigned, or the assigned agent was deleted.
parent: str | None =
None
ID of the parent task when this task is a subtask (tsk_...). null for top-level tasks or when the parent is not readable. Subtasks nest exactly one level.
priority: int | None =
None
Priority level of the task from 0 (highest) to 4 (lowest). Defaults to 2 (medium) when not explicitly set.
project_id: str | None =
None
Optional project ID (prj_...). Membership does not change task visibility.
sandbox: str | None =
None
ID of the developer sandbox this task is scoped to (dsb_...). null for tasks outside a sandbox environment.
source_id: str | None =
None
Source object identity (for example ArchAstro/firstlanding). null when the task has no source.
source_scope: str | None =
None
Container of the work this task is about (for example github.com). null when the task has no source. Set together with source_type and source_id.
source_type: str | None =
None
Kind of source object (for example repository). null when the task has no source.
stalled_since: datetime.datetime | None =
None
Lease expiry for a stalled task, or its last update when no lease expiry exists. Null when not stalled.
status: str =
PydanticUndefined
Current status of the task. One of "open", "in_progress", "in_review", "paused", "failed", "superseding", "done", or "cancelled".
subtasks_count: int | None =
None
Number of readable subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.
target_binary: str | None =
None
Binary that must run this work (for example my-cli). A worker should take the task only when its own target_binary build is at least target_version. null when the task has no target. Set together with target_version.
target_version: str | None =
None
Minimum semantic version of target_binary that can run this work (for example 0.48.9), in canonical MAJOR.MINOR.PATCH[-prerelease][+build] form. null when the task has no target.
team: str | None =
None
ID of the team that owns this task (tem_...). null if the task is not scoped to a team.
class
UserTaskReadyResponseDataItem(pydantic.main.BaseModel):
1082class UserTaskReadyResponseDataItem(BaseModel): 1083 readiness: Literal["ready", "blocked", "leased"] = Field( 1084 ..., description="One of `ready`, `blocked`, or `leased`." 1085 ) 1086 reason: Literal["open_blockers", "active_lease"] | None = Field( 1087 default=None, 1088 description="Stable exclusion reason: `open_blockers` or `active_lease`; omitted when ready.", 1089 ) 1090 task: UserTaskReadyResponseDataItemTask = Field( 1091 ..., description="The task evaluated for readiness." 1092 )
!!! 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):
1095class UserTaskReadyResponse(BaseModel): 1096 """ 1097 Successful response 1098 """ 1099 1100 after_cursor: str | None = None 1101 authoritative: bool = Field( 1102 ..., 1103 description="Always false because projections can lag writes and a later claim can race this read.", 1104 ) 1105 before_cursor: str | None = None 1106 data: list[UserTaskReadyResponseDataItem] 1107 has_more: bool
Successful response
class
UserTaskSearchResponseDataItemCreatedByActorProfilePicture(pydantic.main.BaseModel):
1110class UserTaskSearchResponseDataItemCreatedByActorProfilePicture(BaseModel): 1111 file: str | None = Field( 1112 default=None, 1113 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 1114 ) 1115 height: int | None = Field( 1116 default=None, description="Height of the image in pixels. `null` if not known." 1117 ) 1118 media: str | None = Field( 1119 default=None, 1120 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 1121 ) 1122 mime_type: str | None = Field( 1123 default=None, 1124 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 1125 ) 1126 refresh_url: str | None = Field( 1127 default=None, 1128 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.", 1129 ) 1130 url: str | None = Field( 1131 default=None, 1132 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.", 1133 ) 1134 width: int | None = Field( 1135 default=None, description="Width of the image in pixels. `null` if not known." 1136 )
!!! 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):
1139class UserTaskSearchResponseDataItemCreatedByActor(BaseModel): 1140 alias: str | None = Field( 1141 default=None, 1142 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 1143 ) 1144 id: str | None = Field( 1145 default=None, 1146 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 1147 ) 1148 name: str | None = Field( 1149 default=None, 1150 description="Display name of the actor shown in the UI. `null` if no name is set.", 1151 ) 1152 profile_picture: UserTaskSearchResponseDataItemCreatedByActorProfilePicture | None = Field( 1153 default=None, 1154 description="Profile picture for the actor. `null` if the actor has no profile picture.", 1155 )
!!! 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):
1158class UserTaskSearchResponseDataItemCurrentLease(BaseModel): 1159 expires_at: datetime = Field( 1160 ..., description="Server-calculated lease expiry in ISO 8601 format." 1161 ) 1162 harness: str = Field(..., description="Bounded harness identifier for the coding session.") 1163 session_name: str = Field( 1164 ..., description="Display name supplied by the coding session that holds the lease." 1165 )
!!! 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):
1168class UserTaskSearchResponseDataItemOwnerActorProfilePicture(BaseModel): 1169 file: str | None = Field( 1170 default=None, 1171 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 1172 ) 1173 height: int | None = Field( 1174 default=None, description="Height of the image in pixels. `null` if not known." 1175 ) 1176 media: str | None = Field( 1177 default=None, 1178 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 1179 ) 1180 mime_type: str | None = Field( 1181 default=None, 1182 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 1183 ) 1184 refresh_url: str | None = Field( 1185 default=None, 1186 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.", 1187 ) 1188 url: str | None = Field( 1189 default=None, 1190 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.", 1191 ) 1192 width: int | None = Field( 1193 default=None, description="Width of the image in pixels. `null` if not known." 1194 )
!!! 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):
1197class UserTaskSearchResponseDataItemOwnerActor(BaseModel): 1198 alias: str | None = Field( 1199 default=None, 1200 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 1201 ) 1202 id: str | None = Field( 1203 default=None, 1204 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 1205 ) 1206 name: str | None = Field( 1207 default=None, 1208 description="Display name of the actor shown in the UI. `null` if no name is set.", 1209 ) 1210 profile_picture: UserTaskSearchResponseDataItemOwnerActorProfilePicture | None = Field( 1211 default=None, 1212 description="Profile picture for the actor. `null` if the actor has no profile picture.", 1213 )
!!! 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):
1216class UserTaskSearchResponseDataItem(BaseModel): 1217 agent: str | None = Field( 1218 default=None, 1219 description="ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", 1220 ) 1221 aggregate_version: int | None = Field( 1222 default=None, 1223 description="Event-stream version for optimistic update fencing. Pass this value as `expected_version` on an update to reject concurrent writes.", 1224 ) 1225 blocked_by_count: int | None = Field( 1226 default=None, 1227 description="Number of readable tasks marked as blocking this task, whether or not they are done (see `GET /tasks/{task}/blockers`). Computed on list/show reads; create/update responses may lag one read behind.", 1228 ) 1229 closed_at: datetime | None = Field( 1230 default=None, 1231 description="When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", 1232 ) 1233 comments_count: int | None = Field( 1234 default=None, description="Total number of comments posted on this task." 1235 ) 1236 created_at: datetime | None = Field( 1237 default=None, description="When the task was created (ISO 8601)." 1238 ) 1239 created_by_actor: UserTaskSearchResponseDataItemCreatedByActor | None = Field( 1240 default=None, 1241 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).", 1242 ) 1243 created_by_agent: str | None = Field( 1244 default=None, 1245 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.", 1246 ) 1247 created_by_user: str | None = Field( 1248 default=None, 1249 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.", 1250 ) 1251 current_lease: UserTaskSearchResponseDataItemCurrentLease | None = Field( 1252 default=None, 1253 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.", 1254 ) 1255 description: str | None = Field( 1256 default=None, 1257 description="Long-form description or notes for the task. `null` if no description has been provided.", 1258 ) 1259 due_date: datetime | None = Field( 1260 default=None, 1261 description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", 1262 ) 1263 epic: str | None = Field( 1264 default=None, 1265 description="Free-form grouping label. `null` when the task is not in an epic.", 1266 ) 1267 id: str = Field(..., description="Task ID (`tsk_...`).") 1268 is_blocked: bool | None = Field( 1269 default=None, 1270 description="`true` while at least one blocking task is not yet done. Informational only - a blocked task can still change status - and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on reads, including mutation responses.", 1271 ) 1272 is_stalled: bool | None = Field( 1273 default=None, 1274 description="True exactly when status is in_progress and the task has no lease or its lease expiry is in the past. Derived at read time from status and lease expiry, including on unannotated reads.", 1275 ) 1276 links: dict[str, Any] | None = Field( 1277 default=None, 1278 description="Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.", 1279 ) 1280 metadata: dict[str, Any] | None = Field( 1281 default=None, 1282 description="Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.", 1283 ) 1284 name: str = Field(..., description="Human-readable title of the task.") 1285 org: str | None = Field( 1286 default=None, 1287 description="ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", 1288 ) 1289 owner_actor: UserTaskSearchResponseDataItemOwnerActor | None = Field( 1290 default=None, 1291 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).", 1292 ) 1293 owner_agent: str | None = Field( 1294 default=None, 1295 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.", 1296 ) 1297 owner_user: str | None = Field( 1298 default=None, 1299 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.", 1300 ) 1301 parent: str | None = Field( 1302 default=None, 1303 description="ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks or when the parent is not readable. Subtasks nest exactly one level.", 1304 ) 1305 priority: int | None = Field( 1306 default=None, 1307 description="Priority level of the task from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when not explicitly set.", 1308 ) 1309 project_id: str | None = Field( 1310 default=None, 1311 description="Optional project ID (`prj_...`). Membership does not change task visibility.", 1312 ) 1313 sandbox: str | None = Field( 1314 default=None, 1315 description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", 1316 ) 1317 source_id: str | None = Field( 1318 default=None, 1319 description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", 1320 ) 1321 source_scope: str | None = Field( 1322 default=None, 1323 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`.", 1324 ) 1325 source_type: str | None = Field( 1326 default=None, 1327 description="Kind of source object (for example `repository`). `null` when the task has no source.", 1328 ) 1329 stalled_since: datetime | None = Field( 1330 default=None, 1331 description="Lease expiry for a stalled task, or its last update when no lease expiry exists. Null when not stalled.", 1332 ) 1333 status: str = Field( 1334 ..., 1335 description='Current status of the task. One of `"open"`, `"in_progress"`, `"in_review"`, `"paused"`, `"failed"`, `"superseding"`, `"done"`, or `"cancelled"`.', 1336 ) 1337 subtasks_count: int | None = Field( 1338 default=None, 1339 description="Number of readable subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.", 1340 ) 1341 tags: list[str] | None = Field( 1342 default=None, 1343 description="Labels for grouping and filtering, stored lowercase and de-duplicated. Empty array when untagged.", 1344 ) 1345 target_binary: str | None = Field( 1346 default=None, 1347 description="Binary that must run this work (for example `my-cli`). A worker should take the task only when its own `target_binary` build is at least `target_version`. `null` when the task has no target. Set together with `target_version`.", 1348 ) 1349 target_version: str | None = Field( 1350 default=None, 1351 description="Minimum semantic version of `target_binary` that can run this work (for example `0.48.9`), in canonical `MAJOR.MINOR.PATCH[-prerelease][+build]` form. `null` when the task has no target.", 1352 ) 1353 team: str | None = Field( 1354 default=None, 1355 description="ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", 1356 ) 1357 thread: str | None = Field( 1358 default=None, 1359 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.", 1360 ) 1361 updated_at: datetime | None = Field( 1362 default=None, description="When the task was last modified (ISO 8601)." 1363 ) 1364 user: str | None = Field( 1365 default=None, 1366 description="ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", 1367 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
agent: str | None =
None
ID of the agent that owns this task (agi_...). null if the task is scoped to a team or user.
aggregate_version: int | None =
None
Event-stream version for optimistic update fencing. Pass this value as expected_version on an update to reject concurrent writes.
blocked_by_count: int | None =
None
Number of readable tasks marked as blocking this task, whether or not they are done (see GET /tasks/{task}/blockers). Computed on list/show reads; create/update responses may lag one read behind.
closed_at: datetime.datetime | None =
None
When the task was marked as done or otherwise closed (ISO 8601). null if the task is still open.
created_by_agent: str | None =
None
ID of the agent that created this task (agi_...). null if the task was created by a human user, or if the creating agent was later deleted.
created_by_user: str | None =
None
ID of the user who created this task (usr_...). null if the task was created by an agent, or if creator provenance was cleared after the creator was deleted.
Viewer-safe live coding-session lease summary. null when the task is unleased or the projected lease has expired. Fencing identifiers are never included.
description: str | None =
None
Long-form description or notes for the task. null if no description has been provided.
due_date: datetime.datetime | None =
None
Date and time by which the task should be completed (ISO 8601). null if no due date is set.
is_blocked: bool | None =
None
true while at least one blocking task is not yet done. Informational only - a blocked task can still change status - and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on reads, including mutation responses.
is_stalled: bool | None =
None
True exactly when status is in_progress and the task has no lease or its lease expiry is in the past. Derived at read time from status and lease expiry, including on unannotated reads.
links: dict[str, typing.Any] | None =
None
Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.
metadata: dict[str, typing.Any] | None =
None
Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.
org: str | None =
None
ID of the organization this task belongs to (org_...). null for tasks outside an org context.
owner_agent: str | None =
None
ID of the agent assigned as owner (agi_...). null if the owner is a human user, the task is unassigned, or the assigned agent was deleted.
owner_user: str | None =
None
ID of the user assigned as owner (usr_...). null if the owner is an agent, the task is unassigned, or the assigned agent was deleted.
parent: str | None =
None
ID of the parent task when this task is a subtask (tsk_...). null for top-level tasks or when the parent is not readable. Subtasks nest exactly one level.
priority: int | None =
None
Priority level of the task from 0 (highest) to 4 (lowest). Defaults to 2 (medium) when not explicitly set.
project_id: str | None =
None
Optional project ID (prj_...). Membership does not change task visibility.
sandbox: str | None =
None
ID of the developer sandbox this task is scoped to (dsb_...). null for tasks outside a sandbox environment.
source_id: str | None =
None
Source object identity (for example ArchAstro/firstlanding). null when the task has no source.
source_scope: str | None =
None
Container of the work this task is about (for example github.com). null when the task has no source. Set together with source_type and source_id.
source_type: str | None =
None
Kind of source object (for example repository). null when the task has no source.
stalled_since: datetime.datetime | None =
None
Lease expiry for a stalled task, or its last update when no lease expiry exists. Null when not stalled.
status: str =
PydanticUndefined
Current status of the task. One of "open", "in_progress", "in_review", "paused", "failed", "superseding", "done", or "cancelled".
subtasks_count: int | None =
None
Number of readable subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.
target_binary: str | None =
None
Binary that must run this work (for example my-cli). A worker should take the task only when its own target_binary build is at least target_version. null when the task has no target. Set together with target_version.
target_version: str | None =
None
Minimum semantic version of target_binary that can run this work (for example 0.48.9), in canonical MAJOR.MINOR.PATCH[-prerelease][+build] form. null when the task has no target.
team: str | None =
None
ID of the team that owns this task (tem_...). null if the task is not scoped to a team.
class
UserTaskSearchResponse(pydantic.main.BaseModel):
1370class UserTaskSearchResponse(BaseModel): 1371 """ 1372 Successful response 1373 """ 1374 1375 after_cursor: str | None = None 1376 before_cursor: str | None = None 1377 data: list[UserTaskSearchResponseDataItem] = Field( 1378 ..., description="Array of task objects matching the query and filters." 1379 ) 1380 has_more: bool 1381 query: str
Successful response
class
UserThreadListResponseDataItemParentMessageAclAddItem(pydantic.main.BaseModel):
1384class UserThreadListResponseDataItemParentMessageAclAddItem(BaseModel): 1385 actions: list[str] = Field( 1386 ..., 1387 description='Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.', 1388 ) 1389 principal: str | None = Field( 1390 default=None, 1391 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"`.', 1392 ) 1393 principal_type: str = Field( 1394 ..., 1395 description='The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 1396 )
!!! 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):
1399class UserThreadListResponseDataItemParentMessageAclGrantsItem(BaseModel): 1400 actions: list[str] = Field( 1401 ..., 1402 description='Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.', 1403 ) 1404 principal: str | None = Field( 1405 default=None, 1406 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"`.', 1407 ) 1408 principal_type: str = Field( 1409 ..., 1410 description='The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 1411 )
!!! 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):
1414class UserThreadListResponseDataItemParentMessageAclRemoveItem(BaseModel): 1415 principal: str | None = Field( 1416 default=None, 1417 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"`.', 1418 ) 1419 principal_type: str = Field( 1420 ..., 1421 description='The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 1422 )
!!! 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):
1425class UserThreadListResponseDataItemParentMessageAcl(BaseModel): 1426 add: list[UserThreadListResponseDataItemParentMessageAclAddItem] | None = Field( 1427 default=None, 1428 description="Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", 1429 ) 1430 grants: list[UserThreadListResponseDataItemParentMessageAclGrantsItem] | None = Field( 1431 default=None, 1432 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`.", 1433 ) 1434 remove: list[UserThreadListResponseDataItemParentMessageAclRemoveItem] | None = Field( 1435 default=None, 1436 description="Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`.", 1437 )
!!! 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):
1440class UserThreadListResponseDataItemParentMessageActorsItemProfilePicture(BaseModel): 1441 file: str | None = Field( 1442 default=None, 1443 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 1444 ) 1445 height: int | None = Field( 1446 default=None, description="Height of the image in pixels. `null` if not known." 1447 ) 1448 media: str | None = Field( 1449 default=None, 1450 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 1451 ) 1452 mime_type: str | None = Field( 1453 default=None, 1454 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 1455 ) 1456 refresh_url: str | None = Field( 1457 default=None, 1458 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.", 1459 ) 1460 url: str | None = Field( 1461 default=None, 1462 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.", 1463 ) 1464 width: int | None = Field( 1465 default=None, description="Width of the image in pixels. `null` if not known." 1466 )
!!! 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):
1469class UserThreadListResponseDataItemParentMessageActorsItem(BaseModel): 1470 alias: str | None = Field( 1471 default=None, 1472 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 1473 ) 1474 id: str | None = Field( 1475 default=None, 1476 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 1477 ) 1478 name: str | None = Field( 1479 default=None, 1480 description="Display name of the actor shown in the UI. `null` if no name is set.", 1481 ) 1482 profile_picture: UserThreadListResponseDataItemParentMessageActorsItemProfilePicture | None = ( 1483 Field( 1484 default=None, 1485 description="Profile picture for the actor. `null` if the actor has no profile picture.", 1486 ) 1487 )
!!! 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):
1490class UserThreadListResponseDataItemParentMessageAttachmentsItemImageSource(BaseModel): 1491 file: str | None = Field( 1492 default=None, 1493 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 1494 ) 1495 height: int | None = Field( 1496 default=None, description="Height of the image in pixels. `null` if not known." 1497 ) 1498 media: str | None = Field( 1499 default=None, 1500 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 1501 ) 1502 mime_type: str | None = Field( 1503 default=None, 1504 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 1505 ) 1506 refresh_url: str | None = Field( 1507 default=None, 1508 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.", 1509 ) 1510 url: str | None = Field( 1511 default=None, 1512 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.", 1513 ) 1514 width: int | None = Field( 1515 default=None, description="Width of the image in pixels. `null` if not known." 1516 )
!!! 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):
1519class UserThreadListResponseDataItemParentMessageAttachmentsItemVariantsItemImageSource(BaseModel): 1520 file: str | None = Field( 1521 default=None, 1522 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 1523 ) 1524 height: int | None = Field( 1525 default=None, description="Height of the image in pixels. `null` if not known." 1526 ) 1527 media: str | None = Field( 1528 default=None, 1529 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 1530 ) 1531 mime_type: str | None = Field( 1532 default=None, 1533 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 1534 ) 1535 refresh_url: str | None = Field( 1536 default=None, 1537 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.", 1538 ) 1539 url: str | None = Field( 1540 default=None, 1541 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.", 1542 ) 1543 width: int | None = Field( 1544 default=None, description="Width of the image in pixels. `null` if not known." 1545 )
!!! 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):
1548class UserThreadListResponseDataItemParentMessageAttachmentsItemVariantsItem(BaseModel): 1549 byte_size: int | None = Field(default=None, description="Size of the stored bytes.") 1550 content_type: str | None = Field( 1551 default=None, 1552 description='MIME type of this variant\'s file (e.g., `"image/jpeg"`, `"video/mp4"`). `null` if the file is not loaded.', 1553 ) 1554 created_at: datetime | None = Field( 1555 default=None, description="When this variant was created (ISO 8601)." 1556 ) 1557 duration_ms: int | None = Field( 1558 default=None, 1559 description="Client-declared video duration in milliseconds; not server-probed.", 1560 ) 1561 file: str | None = Field( 1562 default=None, 1563 description="ID of the underlying storage file that backs this variant (`fil_...`).", 1564 ) 1565 filename: str | None = Field( 1566 default=None, 1567 description="Original filename of the uploaded file for this variant. `null` if the file is not loaded.", 1568 ) 1569 height: int | None = Field( 1570 default=None, description="Height of this variant in pixels. `null` if not recorded." 1571 ) 1572 id: str = Field(..., description="Media variant ID (`mvr_...`).") 1573 image_source: ( 1574 UserThreadListResponseDataItemParentMessageAttachmentsItemVariantsItemImageSource | None 1575 ) = Field( 1576 default=None, 1577 description="Resolved image delivery metadata for this variant, including dimensions and CDN URL. `null` for non-image content types.", 1578 ) 1579 sha256: str | None = Field(default=None, description="Lowercase SHA-256 of the stored bytes.") 1580 updated_at: datetime | None = Field( 1581 default=None, description="When this variant was last updated (ISO 8601)." 1582 ) 1583 url: str | None = Field( 1584 default=None, 1585 description="Signed download URL for this variant, resolved at request time. `null` if the file is unavailable.", 1586 ) 1587 url_expires_at: datetime | None = Field( 1588 default=None, description="Expiry of this variant's playable URL." 1589 ) 1590 variant_key: str | None = Field( 1591 default=None, 1592 description='Identifier for this variant\'s processing tier. Common values include `"original"` (the unmodified upload) and `"thumbnail"` (a resized preview).', 1593 ) 1594 width: int | None = Field( 1595 default=None, description="Width of this variant in pixels. `null` if not recorded." 1596 )
!!! 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):
1599class UserThreadListResponseDataItemParentMessageAttachmentsItem(BaseModel): 1600 content_type: str | None = Field( 1601 default=None, 1602 description='MIME type of the attached file, e.g. `"image/png"` or `"application/pdf"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.', 1603 ) 1604 description: str | None = Field( 1605 default=None, 1606 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.", 1607 ) 1608 filename: str | None = Field( 1609 default=None, 1610 description='Original filename of the attached file, e.g. `"report.pdf"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.', 1611 ) 1612 height: int | None = Field( 1613 default=None, 1614 description="Height in pixels of the media item. Present on `media` type only. `null` otherwise.", 1615 ) 1616 id: str = Field(..., description="Unique identifier for this attachment within the message.") 1617 image_height: int | None = Field( 1618 default=None, 1619 description="Height in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", 1620 ) 1621 image_source: UserThreadListResponseDataItemParentMessageAttachmentsItemImageSource | None = ( 1622 Field( 1623 default=None, 1624 description="Image source metadata for inline rendering. Present on `file`, `scraped_link`, `artifact`, and `media` types when the content is an image. `null` otherwise.", 1625 ) 1626 ) 1627 image_url: str | None = Field( 1628 default=None, 1629 description="URL of the preview image extracted from the scraped page. Present on `scraped_link` type only. `null` otherwise.", 1630 ) 1631 image_width: int | None = Field( 1632 default=None, 1633 description="Width in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", 1634 ) 1635 key: str | None = Field( 1636 default=None, 1637 description='For `structured_data` type, what the data is about as set by the sender (for example `"pr:14963"`), copied from the record so it can be read without `object`. Not unique. `null` when unset and on other types.', 1638 ) 1639 media_type: str | None = Field( 1640 default=None, 1641 description='The media category, e.g. `"video"` or `"audio"`. Present on `media` type only; omitted otherwise.', 1642 ) 1643 name: str | None = Field( 1644 default=None, 1645 description="Display name of the media item. Present on `media` type only. `null` otherwise.", 1646 ) 1647 object: dict[str, Any] | None = Field( 1648 default=None, 1649 description="The full embedded object payload. For `task` type, contains the task record. For `action` type, contains the action definition. For `chart` type, contains the chart with its inline `spec`. For `structured_data` type, contains the inline `data` and the `schema_url` or `schema_config` naming its JSON Schema. Omitted on other types.", 1650 ) 1651 title: str | None = Field( 1652 default=None, 1653 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.", 1654 ) 1655 type: str = Field( 1656 ..., 1657 description='The attachment type. One of `"file"`, `"scraped_link"`, `"artifact"`, `"task"`, `"media"`, `"action"`, `"chart"`, or `"structured_data"`. Determines which additional fields are present.', 1658 ) 1659 url: str | None = Field( 1660 default=None, 1661 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.", 1662 ) 1663 variants: ( 1664 list[UserThreadListResponseDataItemParentMessageAttachmentsItemVariantsItem] | None 1665 ) = Field( 1666 default=None, 1667 description="Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only; omitted otherwise.", 1668 ) 1669 version: int | None = Field( 1670 default=None, 1671 description="Version number of the attached artifact at the time of attachment. Present on `artifact` type only. `null` otherwise.", 1672 ) 1673 width: int | None = Field( 1674 default=None, 1675 description="Width in pixels of the media item. Present on `media` type only. `null` otherwise.", 1676 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
content_type: str | None =
None
MIME type of the attached file, e.g. "image/png" or "application/pdf". Present on file, artifact, and media types. null otherwise.
description: str | None =
None
Short description. The page meta-description for scraped_link, the artifact description for artifact, and the task description for task types. null on other types.
filename: str | None =
None
Original filename of the attached file, e.g. "report.pdf". Present on file, artifact, and media types. null otherwise.
height: int | None =
None
Height in pixels of the media item. Present on media type only. null otherwise.
image_height: int | None =
None
Height in pixels of the scraped preview image. Present on scraped_link type only. null otherwise.
Image source metadata for inline rendering. Present on file, scraped_link, artifact, and media types when the content is an image. null otherwise.
image_url: str | None =
None
URL of the preview image extracted from the scraped page. Present on scraped_link type only. null otherwise.
image_width: int | None =
None
Width in pixels of the scraped preview image. Present on scraped_link type only. null otherwise.
key: str | None =
None
For structured_data type, what the data is about as set by the sender (for example "pr:14963"), copied from the record so it can be read without object. Not unique. null when unset and on other types.
media_type: str | None =
None
The media category, e.g. "video" or "audio". Present on media type only; omitted otherwise.
object: dict[str, typing.Any] | None =
None
The full embedded object payload. For task type, contains the task record. For action type, contains the action definition. For chart type, contains the chart with its inline spec. For structured_data type, contains the inline data and the schema_url or schema_config naming its JSON Schema. Omitted on other types.
title: str | None =
None
Display title. The page title for scraped_link, the artifact name for artifact, and the task title for task types. null on other types.
type: str =
PydanticUndefined
The attachment type. One of "file", "scraped_link", "artifact", "task", "media", "action", "chart", or "structured_data". Determines which additional fields are present.
url: str | None =
None
URL to access the resource. A signed download URL for file and artifact types; the original URL for scraped_link; a media playback URL for media. null on task and action types.
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
UserThreadListResponseDataItemParentMessageContextItem(pydantic.main.BaseModel):
1679class UserThreadListResponseDataItemParentMessageContextItem(BaseModel): 1680 attributes: dict[str, Any] | None = Field( 1681 default=None, 1682 description="Scalar key-value fields describing the context, such as route, repository, or pull-request number.", 1683 ) 1684 content: str | None = Field( 1685 default=None, 1686 description="Optional context body. The model receives it as escaped XML data, not a system instruction.", 1687 ) 1688 title: str | None = Field( 1689 default=None, description="Optional human-readable label for this context block." 1690 ) 1691 type: str = Field( 1692 ..., 1693 description="Stable context kind. Must start with a lowercase letter and contain only lowercase letters, numbers, dots, dashes, or underscores.", 1694 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
attributes: dict[str, typing.Any] | None =
None
Scalar key-value fields describing the context, such as route, repository, or pull-request number.
class
UserThreadListResponseDataItemParentMessageReactionsItem(pydantic.main.BaseModel):
1697class UserThreadListResponseDataItemParentMessageReactionsItem(BaseModel): 1698 payload: dict[str, Any] | None = Field( 1699 default=None, 1700 description='Type-specific reaction data. For `"emoji_reaction"` reactions, contains an `emoji` key with the Unicode emoji string (e.g., `" "`).', 1701 ) 1702 type: str = Field( 1703 ..., 1704 description='Reaction type identifier. Currently always `"emoji_reaction"` for emoji-based reactions.', 1705 ) 1706 user: str | None = Field( 1707 default=None, description="Public ID of the user who added the reaction (`usr_...`)." 1708 )
!!! 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):
1711class UserThreadListResponseDataItemParentMessage(BaseModel): 1712 acl: UserThreadListResponseDataItemParentMessageAcl | None = Field( 1713 default=None, 1714 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.", 1715 ) 1716 actors: list[UserThreadListResponseDataItemParentMessageActorsItem] | None = Field( 1717 default=None, 1718 description="Resolved actor descriptors for the message sender, combining identity and display metadata. Always contains exactly one entry.", 1719 ) 1720 agent: str | None = Field( 1721 default=None, 1722 description="ID of the agent user that sent this message (`agi_...`). `null` for messages sent by human users.", 1723 ) 1724 agent_mode: Literal["cli", "embedded"] | None = Field( 1725 default=None, 1726 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.", 1727 ) 1728 attachments: list[UserThreadListResponseDataItemParentMessageAttachmentsItem] | None = Field( 1729 default=None, 1730 description="Files, links, tasks, media, artifacts, and actions attached to this message. Empty array if there are no attachments.", 1731 ) 1732 branched_thread: str | None = Field( 1733 default=None, 1734 description="ID of the thread that was branched from this message (`thr_...`). `null` if this message has not spawned a branch thread.", 1735 ) 1736 content: str | None = Field( 1737 default=None, 1738 description="Text content of the message. `null` for messages that contain only attachments.", 1739 ) 1740 context: list[UserThreadListResponseDataItemParentMessageContextItem] | None = Field( 1741 default=None, 1742 description="Immutable structured context captured when the message was posted. Each entry has `type`, optional `title` and `content`, and scalar `attributes`. Always present; defaults to an empty array. Context is delivered to agents as escaped XML data, not as system instructions.", 1743 ) 1744 created_at: str | None = Field( 1745 default=None, description="When the message was posted (ISO 8601)." 1746 ) 1747 has_replies: bool | None = Field( 1748 default=None, 1749 description="Whether this message has at least one reply. Only present when explicitly requested or computed by the server.", 1750 ) 1751 id: str = Field(..., description="Message ID (`msg_...`).") 1752 idempotency_key: str | None = Field( 1753 default=None, 1754 description="Client-supplied idempotency key used to deduplicate message sends. `null` if the sender did not provide one.", 1755 ) 1756 is_deleted: bool | None = Field( 1757 default=None, 1758 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.", 1759 ) 1760 legacy_agent: str | None = Field( 1761 default=None, 1762 description="Identifier of the legacy chat agent that sent this message, if applicable. `null` for messages sent by users or modern agent users.", 1763 ) 1764 metadata: dict[str, Any] | None = Field( 1765 default=None, 1766 description="Arbitrary key-value metadata attached to the message. Always present; defaults to an empty object when no metadata has been set.", 1767 ) 1768 org: str | None = Field( 1769 default=None, description="ID of the organization that owns this message (`org_...`)." 1770 ) 1771 reactions: list[UserThreadListResponseDataItemParentMessageReactionsItem] | None = Field( 1772 default=None, 1773 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.", 1774 ) 1775 rendering_mode: str | None = Field( 1776 default=None, 1777 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.', 1778 ) 1779 replies: list[dict[str, Any]] | None = Field( 1780 default=None, 1781 description="Inline array of reply messages, each serialized as a full message object. Only present when the server has preloaded replies for this message.", 1782 ) 1783 replies_after_cursor: str | None = Field( 1784 default=None, 1785 description="Opaque pagination cursor to fetch replies posted after the current page. Only present when inline replies are included in the response.", 1786 ) 1787 replies_before_cursor: str | None = Field( 1788 default=None, 1789 description="Opaque pagination cursor to fetch replies posted before the current page. Only present when inline replies are included in the response.", 1790 ) 1791 reply_count: int | None = Field( 1792 default=None, 1793 description="Total number of direct replies to this message. Only present when explicitly requested or computed by the server.", 1794 ) 1795 reply_to: dict[str, Any] | None = Field( 1796 default=None, 1797 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.", 1798 ) 1799 root_message_id: str | None = Field( 1800 default=None, 1801 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.", 1802 ) 1803 sandbox: str | None = Field( 1804 default=None, 1805 description="ID of the developer sandbox this message belongs to (`dsb_...`). `null` for non-sandbox messages.", 1806 ) 1807 team: str | None = Field( 1808 default=None, 1809 description="ID of the team this message is scoped to (`tem_...`). `null` if the message is not team-scoped.", 1810 ) 1811 thread: str | None = Field( 1812 default=None, description="ID of the thread this message belongs to (`thr_...`)." 1813 ) 1814 type: str | None = Field( 1815 default=None, 1816 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.", 1817 ) 1818 user: str | dict[str, Any] | None = Field( 1819 default=None, 1820 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.", 1821 ) 1822 visibility: Literal["default", "private"] | None = Field( 1823 default=None, 1824 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.", 1825 )
!!! 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):
1828class UserThreadListResponseDataItemParticipantsItem(BaseModel): 1829 alias: str | None = Field( 1830 default=None, description="Short handle or alias for the user. `null` if not set." 1831 ) 1832 app: str | None = Field( 1833 default=None, 1834 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.", 1835 ) 1836 app_name: str | None = Field( 1837 default=None, 1838 description="Display name of the user's app. `null` when the app association was not preloaded by the caller.", 1839 ) 1840 created_by_agent_user: str | None = Field( 1841 default=None, 1842 description="Agent user that created this account (`usr_...`). `null` unless an agent created it.", 1843 ) 1844 created_by_developer: str | None = Field( 1845 default=None, 1846 description="Developer account that created this user (`dva_...`). `null` unless created via a developer token.", 1847 ) 1848 created_by_org: str | None = Field( 1849 default=None, 1850 description="Org of the principal that created this user (`org_...`). `null` on legacy rows.", 1851 ) 1852 created_by_team: str | None = Field( 1853 default=None, 1854 description="Team that created this user (`tem_...`). `null` unless created as a team.", 1855 ) 1856 created_by_user: str | None = Field( 1857 default=None, 1858 description="User who created this account (`usr_...`). `null` on self-signup or legacy rows.", 1859 ) 1860 email: str | None = Field(default=None, description="Email address of the user.") 1861 id: str = Field(..., description="User ID (`usr_...`).") 1862 is_system_user: bool | None = Field( 1863 default=None, 1864 description="`true` if this account is an internal system user rather than a human. System users are created automatically by the platform.", 1865 ) 1866 metadata: dict[str, Any] | None = Field( 1867 default=None, 1868 description="Arbitrary key-value metadata attached to the user. Defaults to an empty object.", 1869 ) 1870 name: str | None = Field( 1871 default=None, 1872 description="Full display name of the user. `null` if the user has not set a name.", 1873 ) 1874 org: str | None = Field( 1875 default=None, 1876 description="ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.", 1877 ) 1878 org_name: str | None = Field( 1879 default=None, 1880 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.", 1881 ) 1882 org_role: str | None = Field( 1883 default=None, 1884 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.', 1885 ) 1886 org_slug: str | None = Field( 1887 default=None, 1888 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.", 1889 ) 1890 sandbox: str | None = Field( 1891 default=None, 1892 description="ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.", 1893 ) 1894 sandbox_name: str | None = Field( 1895 default=None, 1896 description="Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.", 1897 )
!!! 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):
1900class UserThreadListResponseDataItemParticipatingAgentsItemAclAddItem(BaseModel): 1901 actions: list[str] = Field( 1902 ..., 1903 description='Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.', 1904 ) 1905 principal: str | None = Field( 1906 default=None, 1907 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"`.', 1908 ) 1909 principal_type: str = Field( 1910 ..., 1911 description='The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 1912 )
!!! 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):
1915class UserThreadListResponseDataItemParticipatingAgentsItemAclGrantsItem(BaseModel): 1916 actions: list[str] = Field( 1917 ..., 1918 description='Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.', 1919 ) 1920 principal: str | None = Field( 1921 default=None, 1922 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"`.', 1923 ) 1924 principal_type: str = Field( 1925 ..., 1926 description='The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 1927 )
!!! 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):
1930class UserThreadListResponseDataItemParticipatingAgentsItemAclRemoveItem(BaseModel): 1931 principal: str | None = Field( 1932 default=None, 1933 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"`.', 1934 ) 1935 principal_type: str = Field( 1936 ..., 1937 description='The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 1938 )
!!! 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):
1941class UserThreadListResponseDataItemParticipatingAgentsItemAcl(BaseModel): 1942 add: list[UserThreadListResponseDataItemParticipatingAgentsItemAclAddItem] | None = Field( 1943 default=None, 1944 description="Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", 1945 ) 1946 grants: list[UserThreadListResponseDataItemParticipatingAgentsItemAclGrantsItem] | None = Field( 1947 default=None, 1948 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`.", 1949 ) 1950 remove: list[UserThreadListResponseDataItemParticipatingAgentsItemAclRemoveItem] | None = Field( 1951 default=None, 1952 description="Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`.", 1953 )
!!! 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):
1956class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionOrgLogo( 1957 BaseModel 1958): 1959 file: str | None = Field( 1960 default=None, 1961 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 1962 ) 1963 height: int | None = Field( 1964 default=None, description="Height of the image in pixels. `null` if not known." 1965 ) 1966 media: str | None = Field( 1967 default=None, 1968 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 1969 ) 1970 mime_type: str | None = Field( 1971 default=None, 1972 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 1973 ) 1974 refresh_url: str | None = Field( 1975 default=None, 1976 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.", 1977 ) 1978 url: str | None = Field( 1979 default=None, 1980 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.", 1981 ) 1982 width: int | None = Field( 1983 default=None, description="Width of the image in pixels. `null` if not known." 1984 )
!!! 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):
1987class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContractParticipantsItem( 1988 BaseModel 1989): 1990 description: str | None = Field( 1991 default=None, 1992 description="Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", 1993 ) 1994 name: str = Field( 1995 ..., 1996 description="The slot's name, as referenced by the workflow. Supply the chosen agent under the top-level `participants[name]` field when invoking.", 1997 ) 1998 required: bool = Field( 1999 ..., 2000 description="Whether the workflow requires this slot to be filled for the run to complete its embedded stages.", 2001 ) 2002 type: str = Field( 2003 ..., 2004 description='The kind of principal the slot accepts. Currently always `"agent_user"` the value supplied at invoke is an agent ID (`agi_...`).', 2005 )
!!! 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):
2008class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContractPrefills( 2009 BaseModel 2010): 2011 participants: dict[str, Any] | None = Field( 2012 default=None, 2013 description="Participant slot-to-agent mappings applied by the platform. Caller values at these slots must match exactly.", 2014 ) 2015 payload: dict[str, Any] | None = Field( 2016 default=None, 2017 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.", 2018 )
!!! 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):
2021class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContract( 2022 BaseModel 2023): 2024 input_schema: dict[str, Any] | None = Field( 2025 default=None, 2026 description="JSON Schema validated against the whole invoke payload, from the automation's `input_schema_config`. `null` when none is configured.", 2027 ) 2028 participants: ( 2029 list[ 2030 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContractParticipantsItem 2031 ] 2032 | None 2033 ) = Field( 2034 default=None, 2035 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.", 2036 ) 2037 prefills: UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContractPrefills = Field( 2038 ..., 2039 description="Owner-controlled payload and participant values the platform applies to every invocation. Supplying a conflicting value is rejected.", 2040 )
!!! 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):
2043class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetails( 2044 BaseModel 2045): 2046 automation_type: str | None = Field( 2047 default=None, 2048 description="Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", 2049 ) 2050 invoke_contract: ( 2051 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContract 2052 | None 2053 ) = Field( 2054 default=None, 2055 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.", 2056 ) 2057 type: Literal["automation"] = Field( 2058 default="automation", 2059 description="Template-details discriminator. Always `automation` for this variant.", 2060 )
!!! 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):
2063class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItem( 2064 BaseModel 2065): 2066 description: str | None = Field( 2067 default=None, 2068 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.", 2069 ) 2070 details: ( 2071 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetails 2072 | None 2073 ) = Field( 2074 default=None, 2075 description="Template-kind-specific details selected by the `type` discriminator. `null` when this template kind has no additional details.", 2076 ) 2077 display_name: str | None = Field( 2078 default=None, 2079 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`.", 2080 ) 2081 id: str | None = Field( 2082 default=None, 2083 description="Template config ID (`cfg_...`). `null` for inline-only templates.", 2084 ) 2085 kind: str = Field( 2086 ..., 2087 description="Template config kind, or `SolutionTemplateRef` / `SolutionTemplatePath` when unresolved.", 2088 ) 2089 lookup_key: str | None = Field( 2090 default=None, 2091 description="Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", 2092 ) 2093 name: str | None = Field( 2094 default=None, 2095 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`.", 2096 ) 2097 readme_url: str | None = Field( 2098 default=None, 2099 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`.", 2100 ) 2101 virtual_path: str | None = Field( 2102 default=None, 2103 description="Stable virtual path assigned to the template config. `null` when no virtual path was set.", 2104 )
!!! 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):
2107class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolution(BaseModel): 2108 category_keys: list[str] | None = Field( 2109 default=None, 2110 description="Category tag keys declared in the Solution body, used to group Solutions in the catalog. An empty array when the body declares none.", 2111 ) 2112 created_at: str | None = Field( 2113 default=None, description="When the Solution config was first imported (ISO 8601)." 2114 ) 2115 description: str | None = Field( 2116 default=None, 2117 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.", 2118 ) 2119 events: dict[str, Any] | None = Field( 2120 default=None, 2121 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.", 2122 ) 2123 id: str = Field(..., description="Solution config ID (`cfg_...`).") 2124 image_url: str | None = Field( 2125 default=None, 2126 description="Absolute URL of the Solution's cover image the bundled asset the body's `image:` field names. A stable, non-expiring capability URL (like `org_logo.url`), safe to hold in caches and OpenGraph tags; it 404s if the Solution stops declaring a cover. `null` when the Solution has no cover image. Org-only rows remain `null`; when a list entry merges an org copy with its system counterpart, it may reuse the system row's public cover URL. Permanent URLs are never minted for private org assets.", 2127 ) 2128 installed_config_ids: list[str] = Field( 2129 ..., 2130 description="Config IDs (`cfg_...`) of this Solution's installations in the viewer's organization. The array is empty when the Solution is visible only from the system catalog.", 2131 ) 2132 kind: str = Field(..., description='Resource type. Always `"Solution"`.') 2133 latest_solution: str | None = Field( 2134 default=None, 2135 description="When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", 2136 ) 2137 latest_version: str | None = Field( 2138 default=None, 2139 description="When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", 2140 ) 2141 lookup_key: str | None = Field( 2142 default=None, 2143 description="The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", 2144 ) 2145 metadata: dict[str, Any] | None = Field( 2146 default=None, 2147 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.", 2148 ) 2149 name: str | None = Field( 2150 default=None, 2151 description="Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", 2152 ) 2153 org: str | None = Field( 2154 default=None, 2155 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.", 2156 ) 2157 org_logo: ( 2158 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionOrgLogo 2159 | None 2160 ) = Field( 2161 default=None, 2162 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.", 2163 ) 2164 org_name: str | None = Field( 2165 default=None, 2166 description="Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", 2167 ) 2168 org_slug: str | None = Field( 2169 default=None, 2170 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.", 2171 ) 2172 owners: list[str] = Field( 2173 ..., 2174 description='Owner scopes this Solution appears under. Members: `"system"` (app-level system scope) and/or `"org"` (viewer\'s org scope).', 2175 ) 2176 readme_url: str | None = Field( 2177 default=None, 2178 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`.", 2179 ) 2180 screenshot_urls: list[str] | None = Field( 2181 default=None, 2182 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.", 2183 ) 2184 solution_id: str | None = Field( 2185 default=None, 2186 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.", 2187 ) 2188 solution_version: str | None = Field( 2189 default=None, 2190 description='Semver string declared in the Solution body (e.g. `"1.2.0"`). `null` when the body does not declare a version.', 2191 ) 2192 tag_keys: list[str] | None = Field( 2193 default=None, 2194 description="Freeform tag keys declared in the Solution body. An empty array when the body declares none.", 2195 ) 2196 template_kind: str | None = Field( 2197 default=None, 2198 description='Wrapped template kind `"AgentTemplate"`, `"AutomationTemplate"`, `"AgentRoutineTemplate"`, `"AgentToolTemplate"`, `"AgentComputerTemplate"`, or `"SolutionTemplateRef"` for ref-mode bundles.', 2199 ) 2200 templates: list[ 2201 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItem 2202 ] = Field( 2203 ..., 2204 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.", 2205 ) 2206 updated_at: str | None = Field( 2207 default=None, description="When the Solution config was last modified (ISO 8601)." 2208 ) 2209 upgrade_available: bool = Field( 2210 ..., 2211 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.", 2212 ) 2213 virtual_path: str | None = Field( 2214 default=None, 2215 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.", 2216 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
category_keys: list[str] | None =
None
Category tag keys declared in the Solution body, used to group Solutions in the catalog. An empty array when the body declares none.
description: str | None =
None
Short tagline or summary declared in the Solution body, used as the card subhead in catalog UIs. null when the Solution body does not set one.
events: dict[str, typing.Any] | None =
None
Custom analytics events declared in the Solution body's events: manifest a map of event key (snake_case) to its definition (label, optional description, optional typed fields). Dashboards use the label as the event's display name. Present as an empty object when the body declares none.
image_url: str | None =
None
Absolute URL of the Solution's cover image the bundled asset the body's image: field names. A stable, non-expiring capability URL (like org_logo.url), safe to hold in caches and OpenGraph tags; it 404s if the Solution stops declaring a cover. null when the Solution has no cover image. Org-only rows remain null; when a list entry merges an org copy with its system counterpart, it may reuse the system row's public cover URL. Permanent URLs are never minted for private org assets.
installed_config_ids: list[str] =
PydanticUndefined
Config IDs (cfg_...) of this Solution's installations in the viewer's organization. The array is empty when the Solution is visible only from the system catalog.
latest_solution: str | None =
None
When upgrade_available is true, the system-scope Solution config ID (cfg_...) that should be used as the upgrade source. null otherwise.
latest_version: str | None =
None
When upgrade_available is true, the higher system-scope solution_version available to upgrade to. null otherwise.
lookup_key: str | None =
None
The lookup key stored on the Solution config, if one was assigned during import. null when no lookup key was set.
metadata: dict[str, typing.Any] | None =
None
Arbitrary key-value metadata declared in the Solution body (e.g. category or display hints). Present as an empty object when the body declares none.
name: str | None =
None
Human-facing display name declared in the Solution body. null when the Solution body does not set one.
org: str | None =
None
Organization ID (org_...) that owns this Solution config, when the Solution is scoped to a specific org. null for system-scope (app-level) Solutions.
org_logo: 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):
2219class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionOrgLogo(BaseModel): 2220 file: str | None = Field( 2221 default=None, 2222 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 2223 ) 2224 height: int | None = Field( 2225 default=None, description="Height of the image in pixels. `null` if not known." 2226 ) 2227 media: str | None = Field( 2228 default=None, 2229 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 2230 ) 2231 mime_type: str | None = Field( 2232 default=None, 2233 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 2234 ) 2235 refresh_url: str | None = Field( 2236 default=None, 2237 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.", 2238 ) 2239 url: str | None = Field( 2240 default=None, 2241 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.", 2242 ) 2243 width: int | None = Field( 2244 default=None, description="Width of the image in pixels. `null` if not known." 2245 )
!!! 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):
2248class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContractParticipantsItem( 2249 BaseModel 2250): 2251 description: str | None = Field( 2252 default=None, 2253 description="Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", 2254 ) 2255 name: str = Field( 2256 ..., 2257 description="The slot's name, as referenced by the workflow. Supply the chosen agent under the top-level `participants[name]` field when invoking.", 2258 ) 2259 required: bool = Field( 2260 ..., 2261 description="Whether the workflow requires this slot to be filled for the run to complete its embedded stages.", 2262 ) 2263 type: str = Field( 2264 ..., 2265 description='The kind of principal the slot accepts. Currently always `"agent_user"` the value supplied at invoke is an agent ID (`agi_...`).', 2266 )
!!! 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):
2269class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContractPrefills( 2270 BaseModel 2271): 2272 participants: dict[str, Any] | None = Field( 2273 default=None, 2274 description="Participant slot-to-agent mappings applied by the platform. Caller values at these slots must match exactly.", 2275 ) 2276 payload: dict[str, Any] | None = Field( 2277 default=None, 2278 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.", 2279 )
!!! 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):
2282class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContract( 2283 BaseModel 2284): 2285 input_schema: dict[str, Any] | None = Field( 2286 default=None, 2287 description="JSON Schema validated against the whole invoke payload, from the automation's `input_schema_config`. `null` when none is configured.", 2288 ) 2289 participants: ( 2290 list[ 2291 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContractParticipantsItem 2292 ] 2293 | None 2294 ) = Field( 2295 default=None, 2296 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.", 2297 ) 2298 prefills: UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContractPrefills = Field( 2299 ..., 2300 description="Owner-controlled payload and participant values the platform applies to every invocation. Supplying a conflicting value is rejected.", 2301 )
!!! 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):
2304class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetails( 2305 BaseModel 2306): 2307 automation_type: str | None = Field( 2308 default=None, 2309 description="Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", 2310 ) 2311 invoke_contract: ( 2312 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContract 2313 | None 2314 ) = Field( 2315 default=None, 2316 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.", 2317 ) 2318 type: Literal["automation"] = Field( 2319 default="automation", 2320 description="Template-details discriminator. Always `automation` for this variant.", 2321 )
!!! 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):
2324class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItem( 2325 BaseModel 2326): 2327 description: str | None = Field( 2328 default=None, 2329 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.", 2330 ) 2331 details: ( 2332 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetails 2333 | None 2334 ) = Field( 2335 default=None, 2336 description="Template-kind-specific details selected by the `type` discriminator. `null` when this template kind has no additional details.", 2337 ) 2338 display_name: str | None = Field( 2339 default=None, 2340 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`.", 2341 ) 2342 id: str | None = Field( 2343 default=None, 2344 description="Template config ID (`cfg_...`). `null` for inline-only templates.", 2345 ) 2346 kind: str = Field( 2347 ..., 2348 description="Template config kind, or `SolutionTemplateRef` / `SolutionTemplatePath` when unresolved.", 2349 ) 2350 lookup_key: str | None = Field( 2351 default=None, 2352 description="Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", 2353 ) 2354 name: str | None = Field( 2355 default=None, 2356 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`.", 2357 ) 2358 readme_url: str | None = Field( 2359 default=None, 2360 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`.", 2361 ) 2362 virtual_path: str | None = Field( 2363 default=None, 2364 description="Stable virtual path assigned to the template config. `null` when no virtual path was set.", 2365 )
!!! 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):
2368class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolution(BaseModel): 2369 category_keys: list[str] | None = Field( 2370 default=None, 2371 description="Category tag keys declared in the Solution body, used to group Solutions in the catalog. An empty array when the body declares none.", 2372 ) 2373 created_at: str | None = Field( 2374 default=None, description="When the Solution config was first imported (ISO 8601)." 2375 ) 2376 description: str | None = Field( 2377 default=None, 2378 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.", 2379 ) 2380 events: dict[str, Any] | None = Field( 2381 default=None, 2382 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.", 2383 ) 2384 id: str = Field(..., description="Solution config ID (`cfg_...`).") 2385 image_url: str | None = Field( 2386 default=None, 2387 description="Absolute URL of the Solution's cover image the bundled asset the body's `image:` field names. A stable, non-expiring capability URL (like `org_logo.url`), safe to hold in caches and OpenGraph tags; it 404s if the Solution stops declaring a cover. `null` when the Solution has no cover image. Org-only rows remain `null`; when a list entry merges an org copy with its system counterpart, it may reuse the system row's public cover URL. Permanent URLs are never minted for private org assets.", 2388 ) 2389 installed_config_ids: list[str] = Field( 2390 ..., 2391 description="Config IDs (`cfg_...`) of this Solution's installations in the viewer's organization. The array is empty when the Solution is visible only from the system catalog.", 2392 ) 2393 kind: str = Field(..., description='Resource type. Always `"Solution"`.') 2394 latest_solution: str | None = Field( 2395 default=None, 2396 description="When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", 2397 ) 2398 latest_version: str | None = Field( 2399 default=None, 2400 description="When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", 2401 ) 2402 lookup_key: str | None = Field( 2403 default=None, 2404 description="The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", 2405 ) 2406 metadata: dict[str, Any] | None = Field( 2407 default=None, 2408 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.", 2409 ) 2410 name: str | None = Field( 2411 default=None, 2412 description="Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", 2413 ) 2414 org: str | None = Field( 2415 default=None, 2416 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.", 2417 ) 2418 org_logo: ( 2419 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionOrgLogo | None 2420 ) = Field( 2421 default=None, 2422 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.", 2423 ) 2424 org_name: str | None = Field( 2425 default=None, 2426 description="Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", 2427 ) 2428 org_slug: str | None = Field( 2429 default=None, 2430 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.", 2431 ) 2432 owners: list[str] = Field( 2433 ..., 2434 description='Owner scopes this Solution appears under. Members: `"system"` (app-level system scope) and/or `"org"` (viewer\'s org scope).', 2435 ) 2436 readme_url: str | None = Field( 2437 default=None, 2438 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`.", 2439 ) 2440 screenshot_urls: list[str] | None = Field( 2441 default=None, 2442 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.", 2443 ) 2444 solution_id: str | None = Field( 2445 default=None, 2446 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.", 2447 ) 2448 solution_version: str | None = Field( 2449 default=None, 2450 description='Semver string declared in the Solution body (e.g. `"1.2.0"`). `null` when the body does not declare a version.', 2451 ) 2452 tag_keys: list[str] | None = Field( 2453 default=None, 2454 description="Freeform tag keys declared in the Solution body. An empty array when the body declares none.", 2455 ) 2456 template_kind: str | None = Field( 2457 default=None, 2458 description='Wrapped template kind `"AgentTemplate"`, `"AutomationTemplate"`, `"AgentRoutineTemplate"`, `"AgentToolTemplate"`, `"AgentComputerTemplate"`, or `"SolutionTemplateRef"` for ref-mode bundles.', 2459 ) 2460 templates: list[ 2461 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItem 2462 ] = Field( 2463 ..., 2464 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.", 2465 ) 2466 updated_at: str | None = Field( 2467 default=None, description="When the Solution config was last modified (ISO 8601)." 2468 ) 2469 upgrade_available: bool = Field( 2470 ..., 2471 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.", 2472 ) 2473 virtual_path: str | None = Field( 2474 default=None, 2475 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.", 2476 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
category_keys: list[str] | None =
None
Category tag keys declared in the Solution body, used to group Solutions in the catalog. An empty array when the body declares none.
description: str | None =
None
Short tagline or summary declared in the Solution body, used as the card subhead in catalog UIs. null when the Solution body does not set one.
events: dict[str, typing.Any] | None =
None
Custom analytics events declared in the Solution body's events: manifest a map of event key (snake_case) to its definition (label, optional description, optional typed fields). Dashboards use the label as the event's display name. Present as an empty object when the body declares none.
image_url: str | None =
None
Absolute URL of the Solution's cover image the bundled asset the body's image: field names. A stable, non-expiring capability URL (like org_logo.url), safe to hold in caches and OpenGraph tags; it 404s if the Solution stops declaring a cover. null when the Solution has no cover image. Org-only rows remain null; when a list entry merges an org copy with its system counterpart, it may reuse the system row's public cover URL. Permanent URLs are never minted for private org assets.
installed_config_ids: list[str] =
PydanticUndefined
Config IDs (cfg_...) of this Solution's installations in the viewer's organization. The array is empty when the Solution is visible only from the system catalog.
latest_solution: str | None =
None
When upgrade_available is true, the system-scope Solution config ID (cfg_...) that should be used as the upgrade source. null otherwise.
latest_version: str | None =
None
When upgrade_available is true, the higher system-scope solution_version available to upgrade to. null otherwise.
lookup_key: str | None =
None
The lookup key stored on the Solution config, if one was assigned during import. null when no lookup key was set.
metadata: dict[str, typing.Any] | None =
None
Arbitrary key-value metadata declared in the Solution body (e.g. category or display hints). Present as an empty object when the body declares none.
name: str | None =
None
Human-facing display name declared in the Solution body. null when the Solution body does not set one.
org: str | None =
None
Organization ID (org_...) that owns this Solution config, when the Solution is scoped to a specific org. null for system-scope (app-level) Solutions.
org_logo: 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):
2479class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionTemplate(BaseModel): 2480 created_at: datetime | None = Field( 2481 default=None, description="When this template config was created (ISO 8601)." 2482 ) 2483 description: str | None = Field( 2484 default=None, 2485 description="Description of the template from the config body. `null` if the current version has no `description` field.", 2486 ) 2487 display_name: str | None = Field( 2488 default=None, 2489 description="Human-readable display name from the config body. `null` if the current version has no `display_name` field.", 2490 ) 2491 id: str = Field(..., description="Template config ID (`cfg_...`).") 2492 kind: str = Field( 2493 ..., description='Config kind identifier for this template (e.g. `"agent_tool_template"`).' 2494 ) 2495 lookup_key: str | None = Field( 2496 default=None, 2497 description="Stable lookup key assigned to this template config. `null` if no lookup key is set.", 2498 ) 2499 name: str | None = Field( 2500 default=None, 2501 description="Template name as stored in the config body. `null` if the current version has no `name` field.", 2502 ) 2503 updated_at: datetime | None = Field( 2504 default=None, description="When this template config was last modified (ISO 8601)." 2505 ) 2506 virtual_path: str | None = Field( 2507 default=None, 2508 description="Virtual filesystem path for this template config. `null` if not set.", 2509 )
!!! 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):
2512class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolution(BaseModel): 2513 current_solution: ( 2514 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolution | None 2515 ) = Field( 2516 default=None, 2517 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.", 2518 ) 2519 solution: UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolution = Field( 2520 ..., 2521 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.", 2522 ) 2523 template: UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionTemplate = Field( 2524 ..., 2525 description="Summary of the AgentTemplate config (`cfg_...`) the agent was last provisioned or updated from.", 2526 )
!!! 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):
2529class UserThreadListResponseDataItemParticipatingAgentsItem(BaseModel): 2530 acl: UserThreadListResponseDataItemParticipatingAgentsItemAcl | None = Field( 2531 default=None, 2532 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.", 2533 ) 2534 app: str | None = Field( 2535 default=None, description="ID of the application that owns this agent (`dap_...`)." 2536 ) 2537 created_at: str | None = Field( 2538 default=None, description="When the agent was created (ISO 8601)." 2539 ) 2540 default_model: str | None = Field( 2541 default=None, 2542 description='Default LLM model identifier used by this agent when no model is specified at runtime (e.g. `"claude-3-7-sonnet-latest"`).', 2543 ) 2544 description: str | None = Field( 2545 default=None, 2546 description="Human-readable description of what the agent does. `null` if not set.", 2547 ) 2548 email: str | None = Field( 2549 default=None, 2550 description="Email address provisioned for this agent. `null` if email delivery is not configured.", 2551 ) 2552 id: str = Field(..., description="Agent ID (`agi_...`).") 2553 identity: str | None = Field( 2554 default=None, 2555 description="System-level identity prompt that shapes the agent's persona and behavior.", 2556 ) 2557 last_applied_template_config: str | None = Field( 2558 default=None, 2559 description="ID of the AgentTemplate config (`cfg_...`) this agent was last provisioned or updated from. `null` for manually created agents.", 2560 ) 2561 lookup_key: str | None = Field( 2562 default=None, 2563 description="Stable, user-defined identifier for this agent within the application. Unique per app.", 2564 ) 2565 metadata: dict[str, Any] | None = Field( 2566 default=None, 2567 description="Arbitrary key-value metadata attached to the agent. Not interpreted by the platform.", 2568 ) 2569 name: str | None = Field( 2570 default=None, description="Human-readable display name for the agent. `null` if not set." 2571 ) 2572 org: str | None = Field( 2573 default=None, 2574 description="ID of the organization this agent belongs to (`org_...`). `null` if the agent is not org-scoped.", 2575 ) 2576 org_name: str | None = Field( 2577 default=None, 2578 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.", 2579 ) 2580 originator: str | None = Field( 2581 default=None, 2582 description="Free-form label identifying the source or author that created this agent (e.g. a username or pipeline name).", 2583 ) 2584 phone_number: str | None = Field( 2585 default=None, 2586 description="Phone number provisioned for this agent. `null` if SMS is not configured.", 2587 ) 2588 sandbox: str | None = Field( 2589 default=None, 2590 description="ID of the sandbox environment this agent is scoped to (`dsb_...`). `null` in production deployments.", 2591 ) 2592 source_solution: UserThreadListResponseDataItemParticipatingAgentsItemSourceSolution | None = ( 2593 Field( 2594 default=None, 2595 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.", 2596 ) 2597 ) 2598 team: str | None = Field( 2599 default=None, 2600 description="ID of the team that owns this agent (`tem_...`). `null` if the agent is not team-scoped.", 2601 ) 2602 template_upgrade_available: bool | None = Field( 2603 default=None, 2604 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`).", 2605 ) 2606 updated_at: str | None = Field( 2607 default=None, description="When the agent was last modified (ISO 8601)." 2608 ) 2609 user: str | None = Field( 2610 default=None, 2611 description="ID of the user that owns this agent (`usr_...`). `null` if the agent is not user-scoped.", 2612 )
!!! 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):
2615class UserThreadListResponseDataItemSettings(BaseModel): 2616 agent_enabled: bool | None = Field( 2617 default=None, 2618 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.", 2619 )
!!! 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):
2622class UserThreadListResponseDataItem(BaseModel): 2623 agent_user: str | None = Field( 2624 default=None, 2625 description="ID of the agent that owns this thread (`agt_...`). `null` for user-owned or team-owned threads.", 2626 ) 2627 created_at: str | None = Field( 2628 default=None, description="When the thread was created (ISO 8601)." 2629 ) 2630 creator: str | dict[str, Any] | None = Field( 2631 default=None, 2632 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.", 2633 ) 2634 description: str | None = Field( 2635 default=None, 2636 description="Optional description or purpose statement for the thread. `null` if not set.", 2637 ) 2638 id: str = Field(..., description="Thread ID (`thr_...`).") 2639 is_channel: bool | None = Field( 2640 default=None, 2641 description="Whether this thread operates as a channel a multi-member broadcast-style conversation.", 2642 ) 2643 is_default: bool | None = Field( 2644 default=None, 2645 description="Whether this is the default thread for its owner. Each user or team has at most one default thread.", 2646 ) 2647 is_transient: bool | None = Field( 2648 default=None, 2649 description="Whether this thread is ephemeral and may be deleted automatically after a period of inactivity or when its TTL expires.", 2650 ) 2651 is_unlisted: bool | None = Field( 2652 default=None, 2653 description="Whether this thread is hidden from public discovery. Unlisted threads are accessible only to direct participants.", 2654 ) 2655 key: str | None = Field( 2656 default=None, 2657 description="Application-defined stable key that uniquely identifies the thread within its scope. Useful for idempotent creation. `null` if not set.", 2658 ) 2659 kind: str | None = Field( 2660 default=None, 2661 description='Thread subtype: `"standard"` for ordinary threads, `"personal"` for a user-and-owned-agents roster, `"feed"` for a post feed with inline replies, `"slack_mirror"` for the membership-strict mirror of a Slack channel, or `"slashwork_mirror"` for the membership-strict mirror of a Slashwork group. `personal` and `feed` are explicit creation options; mirror kinds are server-derived.', 2662 ) 2663 last_activity: str | None = Field( 2664 default=None, 2665 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.", 2666 ) 2667 last_message_preview: str | None = Field( 2668 default=None, 2669 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.", 2670 ) 2671 last_message_sender: str | None = Field( 2672 default=None, 2673 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.", 2674 ) 2675 metadata: dict[str, Any] | None = Field( 2676 default=None, 2677 description="Arbitrary key-value metadata attached to the thread. Shape is application-defined; `null` if no metadata has been set.", 2678 ) 2679 muted: bool | None = Field( 2680 default=None, 2681 description="Whether the authenticated user has muted notifications for this thread. `true` suppresses all notification delivery.", 2682 ) 2683 org: str | None = Field( 2684 default=None, 2685 description="ID of the organization this thread belongs to (`org_...`). `null` for threads outside an org context.", 2686 ) 2687 parent_message: UserThreadListResponseDataItemParentMessage | None = Field( 2688 default=None, 2689 description="The message that spawned this thread as a sub-thread. `null` for top-level threads.", 2690 ) 2691 participant: list[str] | None = Field( 2692 default=None, 2693 description="Array of participant user IDs (`usr_...`) who are members of this thread.", 2694 ) 2695 participants: list[UserThreadListResponseDataItemParticipantsItem] | None = Field( 2696 default=None, 2697 description="Expanded participant user objects for each member of this thread. Populated only when the association is loaded.", 2698 ) 2699 participating_actor: list[str] | None = Field( 2700 default=None, 2701 description="Composite actor identifiers for all participants currently active in this thread. Present only when actor enrichment is requested.", 2702 ) 2703 participating_agents: list[UserThreadListResponseDataItemParticipatingAgentsItem] | None = ( 2704 Field( 2705 default=None, 2706 description="Expanded agent objects for all agents participating in this thread. Present only when agent enrichment is requested.", 2707 ) 2708 ) 2709 role: str | None = Field( 2710 default=None, 2711 description='The authenticated user\'s membership role in this thread, e.g. `"owner"`, `"member"`, or `"viewer"`. `null` if the user is not a member.', 2712 ) 2713 sandbox: str | None = Field( 2714 default=None, 2715 description="ID of the developer sandbox this thread is scoped to (`dsb_...`). `null` for production threads.", 2716 ) 2717 settings: UserThreadListResponseDataItemSettings | None = Field( 2718 default=None, 2719 description="Per-thread configuration settings controlling AI agent behavior for this thread.", 2720 ) 2721 slug: str | None = Field( 2722 default=None, 2723 description="URL-safe slug for the thread, used in human-readable permalinks. `null` if not assigned.", 2724 ) 2725 sub_threads: list[dict[str, Any]] | None = Field( 2726 default=None, 2727 description="Threads that are nested under this thread as replies to a parent message. Present only when sub-thread enrichment is requested.", 2728 ) 2729 tags: list[str] | None = Field( 2730 default=None, 2731 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.', 2732 ) 2733 team: str | None = Field( 2734 default=None, 2735 description="ID of the team that owns this thread (`team_...`). `null` for user-owned or agent-owned threads.", 2736 ) 2737 title: str | None = Field( 2738 default=None, 2739 description="Human-readable name of the thread. `null` if no title has been set.", 2740 ) 2741 ttl: str | None = Field( 2742 default=None, 2743 description="Offset-free expiry timestamp after which the thread may be automatically cleaned up. `null` if the thread does not expire.", 2744 ) 2745 unread_count: int | None = Field( 2746 default=None, 2747 description="Number of messages in this thread that the authenticated user has not yet read. Present only when read-state enrichment is requested.", 2748 ) 2749 updated_at: str | None = Field( 2750 default=None, description="When the thread was last modified (ISO 8601)." 2751 ) 2752 user: str | None = Field( 2753 default=None, 2754 description="ID of the user who owns this thread (`usr_...`). `null` for team-owned or agent-owned threads.", 2755 ) 2756 visibility: Literal["team", "restricted", "private", "org"] = Field( 2757 ..., 2758 description="Who can read the thread: `team` for every owning-team member, `restricted` for team-readable threads with an explicit roster, `private` for roster-only access, or `org` for every member of the owning organization.", 2759 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
agent_user: str | None =
None
ID of the agent that owns this thread (agt_...). null for user-owned or team-owned threads.
creator: str | dict[str, typing.Any] | None =
None
User who created this thread. Returns a user ID (usr_...) by default, or an expanded user object when the association is loaded. null if the creator is unknown.
description: str | None =
None
Optional description or purpose statement for the thread. null if not set.
is_channel: bool | None =
None
Whether this thread operates as a channel a multi-member broadcast-style conversation.
is_default: bool | None =
None
Whether this is the default thread for its owner. Each user or team has at most one default thread.
is_transient: bool | None =
None
Whether this thread is ephemeral and may be deleted automatically after a period of inactivity or when its TTL expires.
is_unlisted: bool | None =
None
Whether this thread is hidden from public discovery. Unlisted threads are accessible only to direct participants.
key: str | None =
None
Application-defined stable key that uniquely identifies the thread within its scope. Useful for idempotent creation. null if not set.
kind: str | None =
None
Thread subtype: "standard" for ordinary threads, "personal" for a user-and-owned-agents roster, "feed" for a post feed with inline replies, "slack_mirror" for the membership-strict mirror of a Slack channel, or "slashwork_mirror" for the membership-strict mirror of a Slashwork group. personal and feed are explicit creation options; mirror kinds are server-derived.
last_activity: str | None =
None
When the most recent message was posted in this thread, falling back to the thread's creation time if it has no messages. Always populated on thread list endpoints (which order by it, after default threads); null on endpoints that don't compute activity enrichment.
last_message_preview: str | None =
None
Single-line snippet of the most recent message's text content (first non-empty line, truncated to 140 characters). Populated on thread list endpoints alongside last_activity; null when the thread has no messages, the latest message has no text content (e.g. attachment-only), or the endpoint doesn't compute activity enrichment.
last_message_sender: str | None =
None
Display name of the sender of the most recent message the same message last_message_preview snippets. Populated on thread list endpoints; null when the thread has no messages or the endpoint doesn't compute activity enrichment.
metadata: dict[str, typing.Any] | None =
None
Arbitrary key-value metadata attached to the thread. Shape is application-defined; null if no metadata has been set.
muted: bool | None =
None
Whether the authenticated user has muted notifications for this thread. true suppresses all notification delivery.
org: str | None =
None
ID of the organization this thread belongs to (org_...). null for threads outside an org context.
participant: list[str] | None =
None
Array of participant user IDs (usr_...) who are members of this thread.
Expanded participant user objects for each member of this thread. Populated only when the association is loaded.
participating_actor: list[str] | None =
None
Composite actor identifiers for all participants currently active in this thread. Present only when actor enrichment is requested.
Expanded agent objects for all agents participating in this thread. Present only when agent enrichment is requested.
role: str | None =
None
The authenticated user's membership role in this thread, e.g. "owner", "member", or "viewer". null if the user is not a member.
sandbox: str | None =
None
ID of the developer sandbox this thread is scoped to (dsb_...). null for production threads.
slug: str | None =
None
URL-safe slug for the thread, used in human-readable permalinks. null if not assigned.
sub_threads: list[dict[str, typing.Any]] | None =
None
Threads that are nested under this thread as replies to a parent message. Present only when sub-thread enrichment is requested.
team: str | None =
None
ID of the team that owns this thread (team_...). null for user-owned or agent-owned threads.
ttl: str | None =
None
Offset-free expiry timestamp after which the thread may be automatically cleaned up. null if the thread does not expire.
unread_count: int | None =
None
Number of messages in this thread that the authenticated user has not yet read. Present only when read-state enrichment is requested.
class
UserThreadListResponse(pydantic.main.BaseModel):
2762class UserThreadListResponse(BaseModel): 2763 """ 2764 Successful response 2765 """ 2766 2767 data: list[UserThreadListResponseDataItem] = Field( 2768 ..., 2769 description="Array of thread objects matching the requested filters and agent narrowings.", 2770 )
Successful response
class
TokenListResponseDataItem(pydantic.main.BaseModel):
2773class TokenListResponseDataItem(BaseModel): 2774 created_at: datetime | None = Field( 2775 default=None, description="When this token was created (ISO 8601)." 2776 ) 2777 created_by_agent_user: str | None = Field( 2778 default=None, 2779 description="Agent user that minted this token (`usr_...`). `null` unless an agent minted it.", 2780 ) 2781 created_by_developer: str | None = Field( 2782 default=None, 2783 description="Developer account that minted this token (`dva_...`). `null` unless minted with a developer token.", 2784 ) 2785 created_by_org: str | None = Field( 2786 default=None, 2787 description="Org of the principal that minted this token (`org_...`). `null` on legacy rows.", 2788 ) 2789 created_by_team: str | None = Field( 2790 default=None, 2791 description="Team that minted this token (`tem_...`). `null` unless minted as a team.", 2792 ) 2793 created_by_user: str | None = Field( 2794 default=None, 2795 description="User who minted this token (`usr_...`). Distinct from the token subject. `null` on legacy rows.", 2796 ) 2797 expires_at: datetime | None = Field( 2798 default=None, 2799 description="When the token expires. `null` on legacy rows that predate stored expiry.", 2800 ) 2801 id: str = Field(..., description="Token ID (`sat_...`).") 2802 last_used_at: datetime | None = Field( 2803 default=None, 2804 description="When this token was last used to authenticate a request. `null` if the token has never been used.", 2805 ) 2806 name: str | None = Field( 2807 default=None, 2808 description="Human-readable label assigned to this token at creation time. `null` when no label was supplied.", 2809 ) 2810 revoked_at: datetime | None = Field( 2811 default=None, 2812 description="When this token was revoked. `null` if the token is still active.", 2813 ) 2814 scopes: str | None = Field( 2815 default=None, 2816 description="Space-separated OAuth scopes stamped on the token. `null` on legacy rows; treat as `full_access`.", 2817 ) 2818 token: str | None = Field( 2819 default=None, 2820 description="Raw bearer token string. Present only in the response to the create request; never returned again after that.", 2821 )
!!! 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):
2824class TokenListResponse(BaseModel): 2825 """ 2826 Successful response 2827 """ 2828 2829 data: list[TokenListResponseDataItem] = Field( 2830 ..., description="Array of access token objects. Raw JWT values are not included." 2831 )
Successful response
class
UserArtifactsResponseDataItemAclAddItem(pydantic.main.BaseModel):
2834class UserArtifactsResponseDataItemAclAddItem(BaseModel): 2835 actions: list[str] = Field( 2836 ..., 2837 description='Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.', 2838 ) 2839 principal: str | None = Field( 2840 default=None, 2841 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"`.', 2842 ) 2843 principal_type: str = Field( 2844 ..., 2845 description='The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 2846 )
!!! 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
UserArtifactsResponseDataItemAclGrantsItem(pydantic.main.BaseModel):
2849class UserArtifactsResponseDataItemAclGrantsItem(BaseModel): 2850 actions: list[str] = Field( 2851 ..., 2852 description='Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.', 2853 ) 2854 principal: str | None = Field( 2855 default=None, 2856 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"`.', 2857 ) 2858 principal_type: str = Field( 2859 ..., 2860 description='The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 2861 )
!!! 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
UserArtifactsResponseDataItemAclRemoveItem(pydantic.main.BaseModel):
2864class UserArtifactsResponseDataItemAclRemoveItem(BaseModel): 2865 principal: str | None = Field( 2866 default=None, 2867 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"`.', 2868 ) 2869 principal_type: str = Field( 2870 ..., 2871 description='The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 2872 )
!!! 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
UserArtifactsResponseDataItemAcl(pydantic.main.BaseModel):
2875class UserArtifactsResponseDataItemAcl(BaseModel): 2876 add: list[UserArtifactsResponseDataItemAclAddItem] | None = Field( 2877 default=None, 2878 description="Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", 2879 ) 2880 grants: list[UserArtifactsResponseDataItemAclGrantsItem] | None = Field( 2881 default=None, 2882 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`.", 2883 ) 2884 remove: list[UserArtifactsResponseDataItemAclRemoveItem] | None = Field( 2885 default=None, 2886 description="Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`.", 2887 )
!!! 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
UserArtifactsResponseDataItemImageSource(pydantic.main.BaseModel):
2890class UserArtifactsResponseDataItemImageSource(BaseModel): 2891 file: str | None = Field( 2892 default=None, 2893 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 2894 ) 2895 height: int | None = Field( 2896 default=None, description="Height of the image in pixels. `null` if not known." 2897 ) 2898 media: str | None = Field( 2899 default=None, 2900 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 2901 ) 2902 mime_type: str | None = Field( 2903 default=None, 2904 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 2905 ) 2906 refresh_url: str | None = Field( 2907 default=None, 2908 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.", 2909 ) 2910 url: str | None = Field( 2911 default=None, 2912 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.", 2913 ) 2914 width: int | None = Field( 2915 default=None, description="Width of the image in pixels. `null` if not known." 2916 )
!!! 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):
2919class UserArtifactsResponseDataItem(BaseModel): 2920 acl: UserArtifactsResponseDataItemAcl | None = Field( 2921 default=None, 2922 description="Access control list for the artifact. Contains a `grants` array where each entry specifies `principal_type`, `principal`, and `actions` (`read`, `write`). `null` when the artifact has no grants or the viewer is not its owner.", 2923 ) 2924 agent: str | None = Field( 2925 default=None, 2926 description="ID of the agent that produced this artifact (`agt_...`). `null` if not agent-produced.", 2927 ) 2928 content_type: str | None = Field( 2929 default=None, 2930 description='MIME type of the current version\'s file, e.g. `"text/csv"` or `"image/png"`. `null` if no file is attached.', 2931 ) 2932 created_at: datetime | None = Field( 2933 default=None, description="When the artifact was first created (ISO 8601)." 2934 ) 2935 current_version: str | None = Field( 2936 default=None, 2937 description="ID of the current (latest published) artifact version (`artv_...`). `null` if no version has been published.", 2938 ) 2939 description: str | None = Field( 2940 default=None, 2941 description="Optional longer description of the artifact's contents or purpose. `null` if not set.", 2942 ) 2943 file: str | None = Field( 2944 default=None, 2945 description="Storage file ID for the current version (`fil_...`). `null` if no file is attached.", 2946 ) 2947 file_name: str | None = Field( 2948 default=None, 2949 description='Original filename of the current version\'s file, e.g. `"output.csv"`. `null` if no file is attached.', 2950 ) 2951 file_url: str | None = Field( 2952 default=None, 2953 description="Short-lived signed URL for downloading the current version's file. `null` if no file is attached.", 2954 ) 2955 group_key: str | None = Field( 2956 default=None, 2957 description="Optional nonunique, case-sensitive grouping key, limited to 1024 UTF-8 bytes. Null when unset; belongs to the artifact, not a content version.", 2958 ) 2959 id: str = Field(..., description="Artifact ID (`art_...`).") 2960 image_source: UserArtifactsResponseDataItemImageSource | None = Field( 2961 default=None, 2962 description='Image source metadata for rendering the current version\'s file inline. Present only when `content_type` starts with `"image/"`. `null` otherwise.', 2963 ) 2964 name: str | None = Field( 2965 default=None, 2966 description='Human-readable name for the artifact, e.g. `"Q2 Report"`. `null` if not set.', 2967 ) 2968 org: str | None = Field( 2969 default=None, description="ID of the organization this artifact belongs to (`org_...`)." 2970 ) 2971 sandbox: str | None = Field( 2972 default=None, 2973 description="Identifier of the sandbox environment associated with this artifact. `null` if not sandbox-scoped.", 2974 ) 2975 system: bool | None = Field( 2976 default=None, 2977 description="True when the artifact has no user, team, or agent owner. An organization may own a system artifact.", 2978 ) 2979 team: str | None = Field( 2980 default=None, 2981 description="ID of the team that owns this artifact (`tea_...`). `null` if not team-scoped.", 2982 ) 2983 thread: str | None = Field( 2984 default=None, 2985 description="ID of the thread in which this artifact was created (`thr_...`). `null` if not thread-scoped.", 2986 ) 2987 updated_at: datetime | None = Field( 2988 default=None, description="When the artifact record was last modified (ISO 8601)." 2989 ) 2990 user: str | None = Field( 2991 default=None, 2992 description="ID of the user who created this artifact (`usr_...`). `null` if not user-scoped.", 2993 ) 2994 version: int | None = Field( 2995 default=None, 2996 description="Current version number of the artifact. Increments each time a new version is published.", 2997 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
Access control list for the artifact. Contains a grants array where each entry specifies principal_type, principal, and actions (read, write). null when the artifact has no grants or the viewer is not its owner.
agent: str | None =
None
ID of the agent that produced this artifact (agt_...). null if not agent-produced.
content_type: str | None =
None
MIME type of the current version's file, e.g. "text/csv" or "image/png". null if no file is attached.
current_version: str | None =
None
ID of the current (latest published) artifact version (artv_...). null if no version has been published.
description: str | None =
None
Optional longer description of the artifact's contents or purpose. null if not set.
file: str | None =
None
Storage file ID for the current version (fil_...). null if no file is attached.
file_name: str | None =
None
Original filename of the current version's file, e.g. "output.csv". null if no file is attached.
file_url: str | None =
None
Short-lived signed URL for downloading the current version's file. null if no file is attached.
group_key: str | None =
None
Optional nonunique, case-sensitive grouping key, limited to 1024 UTF-8 bytes. Null when unset; belongs to the artifact, not a content version.
Image source metadata for rendering the current version's file inline. Present only when content_type starts with "image/". null otherwise.
sandbox: str | None =
None
Identifier of the sandbox environment associated with this artifact. null if not sandbox-scoped.
system: bool | None =
None
True when the artifact has no user, team, or agent owner. An organization may own a system artifact.
thread: str | None =
None
ID of the thread in which this artifact was created (thr_...). null if not thread-scoped.
class
UserArtifactsResponse(pydantic.main.BaseModel):
3000class UserArtifactsResponse(BaseModel): 3001 """ 3002 Successful response 3003 """ 3004 3005 data: list[UserArtifactsResponseDataItem] = Field( 3006 ..., description="Array of artifact objects belonging to the user." 3007 )
Successful response
class
UserOrgsResponseDataItem(pydantic.main.BaseModel):
3010class UserOrgsResponseDataItem(BaseModel): 3011 created_at: datetime | None = Field( 3012 default=None, description="When this organization was created (ISO 8601)." 3013 ) 3014 description: str | None = Field( 3015 default=None, 3016 description="Short human-readable description of the organization. `null` if not set.", 3017 ) 3018 domain: str | None = Field( 3019 default=None, 3020 description='Primary domain associated with the organization, e.g. `"acme.com"`. `null` if not configured.', 3021 ) 3022 id: str = Field(..., description="Organization ID (`org_...`).") 3023 industry: str | None = Field( 3024 default=None, 3025 description='Industry category the organization belongs to, e.g. `"fintech"` or `"healthcare"`. `null` if not set.', 3026 ) 3027 kind: Literal["company", "personal"] = Field( 3028 ..., description="Whether this is a company-domain org or a person-owned personal org." 3029 ) 3030 name: str | None = Field( 3031 default=None, 3032 description="Display name of the organization. `null` if the org has not set a name.", 3033 ) 3034 onboarding_solution_lookup_key: str | None = Field( 3035 default=None, 3036 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.", 3037 ) 3038 onboarding_track: str | None = Field( 3039 default=None, 3040 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.', 3041 ) 3042 owned_products: list[str] | None = Field( 3043 default=None, 3044 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.', 3045 ) 3046 owner_user: str | None = Field( 3047 default=None, description="Owner user ID for a personal org. `null` for company orgs." 3048 ) 3049 sandbox: str | None = Field( 3050 default=None, 3051 description="ID of the sandbox environment scoped to this organization (`snd_...`). `null` for organizations in production mode.", 3052 ) 3053 slug: str | None = Field( 3054 default=None, 3055 description="URL-safe identifier for the organization, used in vanity URLs and slug-based lookups.", 3056 ) 3057 status: str | None = Field( 3058 default=None, 3059 description='Current lifecycle status of the organization, e.g. `"active"` or `"suspended"`. `null` if the status has not been set.', 3060 ) 3061 updated_at: datetime | None = Field( 3062 default=None, description="When this organization was last modified (ISO 8601)." 3063 ) 3064 website: str | None = Field( 3065 default=None, description="Public website URL for the organization. `null` if not set." 3066 )
!!! 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.
kind: Literal['company', 'personal'] =
PydanticUndefined
Whether this is a company-domain org or a person-owned personal org.
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):
3069class UserOrgsResponse(BaseModel): 3070 """ 3071 Successful response 3072 """ 3073 3074 data: list[UserOrgsResponseDataItem] = Field( 3075 ..., 3076 description="Array of organization objects the user belongs to. Contains at most one item.", 3077 )
Successful response
class
UserTaskEpicsResponseDataItemNextReadyItem(pydantic.main.BaseModel):
3080class UserTaskEpicsResponseDataItemNextReadyItem(BaseModel): 3081 id: str 3082 name: str 3083 priority: int 3084 status: str
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
class
UserTaskEpicsResponseDataItemRootBlockersItem(pydantic.main.BaseModel):
3087class UserTaskEpicsResponseDataItemRootBlockersItem(BaseModel): 3088 downstream_count: int 3089 id: str 3090 name: str 3091 priority: int 3092 status: str
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
class
UserTaskEpicsResponseDataItem(pydantic.main.BaseModel):
3095class UserTaskEpicsResponseDataItem(BaseModel): 3096 blocked_count: int 3097 counts: dict[str, Any] = Field( 3098 ..., description="Task counts keyed by status, including closed tasks." 3099 ) 3100 epic: str 3101 next_ready: list[UserTaskEpicsResponseDataItemNextReadyItem] 3102 root_blockers: list[UserTaskEpicsResponseDataItemRootBlockersItem] 3103 root_blockers_partial: bool = Field( 3104 ..., description="True when root ranking used a truncated in-epic graph." 3105 ) 3106 top_open_priority: int | None = None 3107 updated_at: datetime
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
counts: dict[str, typing.Any] =
PydanticUndefined
Task counts keyed by status, including closed tasks.
class
UserTaskEpicsResponse(pydantic.main.BaseModel):
3110class UserTaskEpicsResponse(BaseModel): 3111 """ 3112 Successful response 3113 """ 3114 3115 after_cursor: str | None = None 3116 before_cursor: str | None = None 3117 data: list[UserTaskEpicsResponseDataItem] 3118 has_more: bool 3119 no_epic_open_count: int
Successful response
class
AsyncIntegrationResource:
3122class AsyncIntegrationResource: 3123 def __init__(self, http: HttpClient): 3124 self._http = http 3125 3126 async def access_token(self, user: str, provider: str) -> IntegrationAccessTokenResponse: 3127 """ 3128 Retrieve a GitHub integration access token 3129 Returns a valid GitHub access token for one integration owned by the 3130 authenticated user. Expired tokens are refreshed before the response is 3131 returned. 3132 This endpoint accepts the user's own bearer token, or the app's secret key 3133 acting server-to-server for one of its users. Developer, agent, team, and 3134 cross-user viewers cannot retrieve the credential. Responses are marked 3135 `Cache-Control: no-store`. 3136 3137 Args: 3138 user: User ID (`usr_...`). The authenticated user, or a user of the app whose secret key is presented. 3139 provider: Integration provider. Only `github` is accepted. 3140 3141 Returns: 3142 Successful response 3143 """ 3144 return await self._http.request( 3145 f"/api/v1/users/{user}/integrations/{provider}/access_token", 3146 response_type=IntegrationAccessTokenResponse, 3147 )
AsyncIntegrationResource(http: archastro.platform.runtime.http_client.HttpClient)
3126 async def access_token(self, user: str, provider: str) -> IntegrationAccessTokenResponse: 3127 """ 3128 Retrieve a GitHub integration access token 3129 Returns a valid GitHub access token for one integration owned by the 3130 authenticated user. Expired tokens are refreshed before the response is 3131 returned. 3132 This endpoint accepts the user's own bearer token, or the app's secret key 3133 acting server-to-server for one of its users. Developer, agent, team, and 3134 cross-user viewers cannot retrieve the credential. Responses are marked 3135 `Cache-Control: no-store`. 3136 3137 Args: 3138 user: User ID (`usr_...`). The authenticated user, or a user of the app whose secret key is presented. 3139 provider: Integration provider. Only `github` is accepted. 3140 3141 Returns: 3142 Successful response 3143 """ 3144 return await self._http.request( 3145 f"/api/v1/users/{user}/integrations/{provider}/access_token", 3146 response_type=IntegrationAccessTokenResponse, 3147 )
Retrieve a GitHub integration access token
Returns a valid GitHub access token for one integration owned by the
authenticated user. Expired tokens are refreshed before the response is
returned.
This endpoint accepts the user's own bearer token, or the app's secret key
acting server-to-server for one of its users. Developer, agent, team, and
cross-user viewers cannot retrieve the credential. Responses are marked
Cache-Control: no-store.
Arguments:
- user: User ID (
usr_...). The authenticated user, or a user of the app whose secret key is presented. - provider: Integration provider. Only
githubis accepted.
Returns:
Successful response
class
AsyncUserSshKeyResource:
3150class AsyncUserSshKeyResource: 3151 def __init__(self, http: HttpClient): 3152 self._http = http 3153 3154 async def list( 3155 self, user: str, *, limit: int | None = None, after_cursor: str | None = None 3156 ) -> UserSshKeyListResponse: 3157 """ 3158 List registered SSH keys 3159 Returns a cursor-paginated page of SSH-key metadata for the authenticated user. 3160 3161 Args: 3162 user: User ID (`usr_...`) or `me`. 3163 limit: Maximum keys per page. Defaults to 50; maximum is 100. 3164 after_cursor: Opaque cursor for the next page of older keys. 3165 3166 Returns: 3167 Successful response 3168 """ 3169 query: dict[str, object] = {} 3170 if limit is not None: 3171 query["limit"] = limit 3172 if after_cursor is not None: 3173 query["after_cursor"] = after_cursor 3174 return await self._http.request( 3175 f"/api/v1/users/{user}/ssh_keys", 3176 query=query, 3177 response_type=UserSshKeyListResponse, 3178 ) 3179 3180 async def create(self, user: str, input: UserSshKeyCreateInput) -> UserSSHKey: 3181 """ 3182 Register an SSH public key 3183 Registers one comment-free Ed25519 public key for Git-over-SSH. The key is 3184 encrypted before storage; responses expose only its label, algorithm and 3185 OpenSSH SHA-256 fingerprint. 3186 The caller must be the user named by `user` and must present a first-party 3187 session or a `full_access` personal access token. 3188 3189 Args: 3190 user: User ID (`usr_...`) or `me`. 3191 input: Request body. 3192 input.label: A label such as `Work laptop`. 3193 input.public_key: One `ssh-ed25519 <base64>` public key without options or a comment. 3194 3195 Returns: 3196 Metadata for the registered key; no key material. 3197 """ 3198 return await self._http.request( 3199 f"/api/v1/users/{user}/ssh_keys", 3200 method="POST", 3201 body=input, 3202 response_type=UserSSHKey, 3203 )
AsyncUserSshKeyResource(http: archastro.platform.runtime.http_client.HttpClient)
async def
list( self, user: str, *, limit: int | None = None, after_cursor: str | None = None) -> UserSshKeyListResponse:
3154 async def list( 3155 self, user: str, *, limit: int | None = None, after_cursor: str | None = None 3156 ) -> UserSshKeyListResponse: 3157 """ 3158 List registered SSH keys 3159 Returns a cursor-paginated page of SSH-key metadata for the authenticated user. 3160 3161 Args: 3162 user: User ID (`usr_...`) or `me`. 3163 limit: Maximum keys per page. Defaults to 50; maximum is 100. 3164 after_cursor: Opaque cursor for the next page of older keys. 3165 3166 Returns: 3167 Successful response 3168 """ 3169 query: dict[str, object] = {} 3170 if limit is not None: 3171 query["limit"] = limit 3172 if after_cursor is not None: 3173 query["after_cursor"] = after_cursor 3174 return await self._http.request( 3175 f"/api/v1/users/{user}/ssh_keys", 3176 query=query, 3177 response_type=UserSshKeyListResponse, 3178 )
List registered SSH keys Returns a cursor-paginated page of SSH-key metadata for the authenticated user.
Arguments:
- user: User ID (
usr_...) orme. - limit: Maximum keys per page. Defaults to 50; maximum is 100.
- after_cursor: Opaque cursor for the next page of older keys.
Returns:
Successful response
async def
create( self, user: str, input: UserSshKeyCreateInput) -> archastro.platform.types.users.UserSSHKey:
3180 async def create(self, user: str, input: UserSshKeyCreateInput) -> UserSSHKey: 3181 """ 3182 Register an SSH public key 3183 Registers one comment-free Ed25519 public key for Git-over-SSH. The key is 3184 encrypted before storage; responses expose only its label, algorithm and 3185 OpenSSH SHA-256 fingerprint. 3186 The caller must be the user named by `user` and must present a first-party 3187 session or a `full_access` personal access token. 3188 3189 Args: 3190 user: User ID (`usr_...`) or `me`. 3191 input: Request body. 3192 input.label: A label such as `Work laptop`. 3193 input.public_key: One `ssh-ed25519 <base64>` public key without options or a comment. 3194 3195 Returns: 3196 Metadata for the registered key; no key material. 3197 """ 3198 return await self._http.request( 3199 f"/api/v1/users/{user}/ssh_keys", 3200 method="POST", 3201 body=input, 3202 response_type=UserSSHKey, 3203 )
Register an SSH public key
Registers one comment-free Ed25519 public key for Git-over-SSH. The key is
encrypted before storage; responses expose only its label, algorithm and
OpenSSH SHA-256 fingerprint.
The caller must be the user named by user and must present a first-party
session or a full_access personal access token.
Arguments:
- user: User ID (
usr_...) orme. - input: Request body.
- input.label: A label such as
Work laptop. - input.public_key: One
ssh-ed25519 <base64>public key without options or a comment.
Returns:
Metadata for the registered key; no key material.
class
AsyncUserTaskResource:
3206class AsyncUserTaskResource: 3207 def __init__(self, http: HttpClient): 3208 self._http = http 3209 3210 async def list( 3211 self, 3212 user: str, 3213 *, 3214 team: str | None = None, 3215 org: str | None = None, 3216 status: str | None = None, 3217 owner_user: str | None = None, 3218 owner_agent: str | None = None, 3219 priority: int | None = None, 3220 tag: str | None = None, 3221 parent: str | None = None, 3222 source_scope: str | None = None, 3223 source_type: str | None = None, 3224 source_id: str | None = None, 3225 epic: str | None = None, 3226 search: str | None = None, 3227 sort: str | None = None, 3228 order: str | None = None, 3229 due_before: str | None = None, 3230 due_after: str | None = None, 3231 overdue: bool | None = None, 3232 ready: bool | None = None, 3233 attention: bool | None = None, 3234 limit: int | None = None, 3235 after_cursor: str | None = None, 3236 ) -> UserTaskListResponse: 3237 """ 3238 List an owner's tasks 3239 Returns tasks owned by the specified user or team. You can narrow results using the 3240 optional filters below. By default results are returned in reverse chronological 3241 order (most recently created first); use `sort` and `order` to sort by due date or 3242 priority instead. 3243 User-authenticated callers may list their personal tasks or tasks for teams they 3244 have joined. Privileged callers provide the owner in the route; the owner's 3245 organization is implied by that principal. An explicit `org` is optional and, 3246 when set, must match the owner's organization. 3247 3248 Args: 3249 user: User ID (`usr_...`) for user-scoped tasks. 3250 team: Team ID (`tem_...`). Only tasks belonging to this team are returned. 3251 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. 3252 status: Filter tasks by status. One of `"open"`, `"in_progress"`, `"in_review"`, or `"done"`. Omit to return tasks in all statuses. 3253 owner_user: Filter tasks assigned to a specific user. Provide the user's public ID (`usr_...`). 3254 owner_agent: Filter tasks assigned to a specific agent. Provide the agent's public ID (`agi_...`). 3255 priority: Filter tasks by priority, from 0 (highest) to 4 (lowest). 3256 tag: Return only tasks carrying this tag (matched against the canonical lowercase form). 3257 parent: Return only subtasks of the given task (`tsk_...`), or pass `none` to return only top-level tasks. 3258 source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 3259 source_type: Return only tasks whose source matches this object kind. Must be supplied with the other source filters. 3260 source_id: Return only tasks whose source matches this object identity. Must be supplied with the other source filters. 3261 epic: Return only tasks with this exact epic label. 3262 search: Restrict results to tasks whose name or description contains this string. 3263 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. 3264 order: Sort direction, `"asc"` or `"desc"`. Defaults to `"desc"` for `created` and `"asc"` for `due_date` and `priority`. 3265 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. 3266 due_after: Return only tasks with a due date strictly after this ISO 8601 datetime or date. Tasks without a due date are excluded. 3267 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. 3268 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. 3269 attention: When true, return paused, failed, or in-progress tasks with no lease or a past lease expiry. 3270 limit: Maximum number of tasks to return. Capped at 100. 3271 after_cursor: Opaque cursor returned by the previous page. 3272 3273 Returns: 3274 Successful response 3275 """ 3276 query: dict[str, object] = {} 3277 if team is not None: 3278 query["team"] = team 3279 if org is not None: 3280 query["org"] = org 3281 if status is not None: 3282 query["status"] = status 3283 if owner_user is not None: 3284 query["owner_user"] = owner_user 3285 if owner_agent is not None: 3286 query["owner_agent"] = owner_agent 3287 if priority is not None: 3288 query["priority"] = priority 3289 if tag is not None: 3290 query["tag"] = tag 3291 if parent is not None: 3292 query["parent"] = parent 3293 if source_scope is not None: 3294 query["source_scope"] = source_scope 3295 if source_type is not None: 3296 query["source_type"] = source_type 3297 if source_id is not None: 3298 query["source_id"] = source_id 3299 if epic is not None: 3300 query["epic"] = epic 3301 if search is not None: 3302 query["search"] = search 3303 if sort is not None: 3304 query["sort"] = sort 3305 if order is not None: 3306 query["order"] = order 3307 if due_before is not None: 3308 query["due_before"] = due_before 3309 if due_after is not None: 3310 query["due_after"] = due_after 3311 if overdue is not None: 3312 query["overdue"] = overdue 3313 if ready is not None: 3314 query["ready"] = ready 3315 if attention is not None: 3316 query["attention"] = attention 3317 if limit is not None: 3318 query["limit"] = limit 3319 if after_cursor is not None: 3320 query["after_cursor"] = after_cursor 3321 return await self._http.request( 3322 f"/api/v1/users/{user}/tasks", 3323 query=query, 3324 response_type=UserTaskListResponse, 3325 ) 3326 3327 async def create(self, user: str, input: UserTaskCreateInput) -> Task: 3328 """ 3329 Create a task for an owner 3330 Creates a new task owned by the specified user or team and returns the full 3331 task object. User-authenticated calls are attributed to the authenticated 3332 user or agent. App-scoped developer and server-to-server callers must provide 3333 the task's explicit `org` scope and an explicit `user` or `agent` actor for 3334 team tasks; a user-owned task reuses the user in the route unless an explicit 3335 agent is supplied. Every referenced principal is validated against the app, 3336 owner, and team membership before creation. 3337 3338 Args: 3339 user: User ID (`usr_...`) for user-scoped tasks. 3340 input: Request body. 3341 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. 3342 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. 3343 input.task: Attributes for the task to create. `name` is required; all other fields are optional. 3344 input.team: Team ID (`tem_...`). The task will be owned by this team. 3345 3346 Returns: 3347 The newly created task. 3348 """ 3349 return await self._http.request( 3350 f"/api/v1/users/{user}/tasks", 3351 method="POST", 3352 body=input, 3353 response_type=Task, 3354 ) 3355 3356 async def blocker_cycles( 3357 self, 3358 user: str, 3359 *, 3360 team: str | None = None, 3361 org: str | None = None, 3362 limit: int | None = None, 3363 after_cursor: str | None = None, 3364 ) -> UserTaskBlockerCyclesResponse: 3365 """ 3366 List task blocker cycles 3367 Runs an on-demand diagnostic over unfinished tasks owned by the specified 3368 team or user and returns a forward cursor-paginated page of complete cyclic 3369 blocker components. Detection is bounded to owners with at most 100 3370 unfinished tasks. This endpoint is read-only: cycles do not prevent task 3371 updates, lease acquisition, or completion. 3372 3373 Args: 3374 user: User ID (`usr_...`) for user-scoped tasks. 3375 team: Team ID (`tem_...`) owning the tasks. 3376 org: Optional organization context for privileged callers. 3377 limit: Maximum cycle components to return. Defaults to 50; maximum is 100. 3378 after_cursor: Opaque cursor returned by the preceding page. 3379 3380 Returns: 3381 Successful response 3382 """ 3383 query: dict[str, object] = {} 3384 if team is not None: 3385 query["team"] = team 3386 if org is not None: 3387 query["org"] = org 3388 if limit is not None: 3389 query["limit"] = limit 3390 if after_cursor is not None: 3391 query["after_cursor"] = after_cursor 3392 return await self._http.request( 3393 f"/api/v1/users/{user}/tasks/blocker_cycles", 3394 query=query, 3395 response_type=UserTaskBlockerCyclesResponse, 3396 ) 3397 3398 async def by_source(self, user: str, input: UserTaskBySourceInput) -> TaskEnsureResult: 3399 """ 3400 Find or create a task by source 3401 Atomically creates one task per owner, tenant and source. Retries return the current task without updating it. Historical tasks created through ordinary create are not adopted. 3402 3403 Args: 3404 user: User ID (`usr_...`) for user-scoped tasks. 3405 input: Request body. 3406 input.agent: Explicit acting agent for privileged callers. 3407 input.description: Initial task description. 3408 input.epic: Initial epic grouping. 3409 input.name: Initial task name. 3410 input.org: Explicit organization for privileged callers. 3411 input.source_id: Source identity, for example owner/repo#123. 3412 input.source_scope: Source scope, for example github. 3413 input.source_type: Source type, for example pull_request. 3414 input.status: Initial task status. 3415 input.team: Team owner. 3416 3417 Returns: 3418 The task and whether this request created it. 3419 """ 3420 return await self._http.request( 3421 f"/api/v1/users/{user}/tasks/by-source", 3422 method="PUT", 3423 body=input, 3424 response_type=TaskEnsureResult, 3425 ) 3426 3427 async def ready( 3428 self, 3429 user: str, 3430 *, 3431 team: str | None = None, 3432 org: str | None = None, 3433 explain: bool | None = None, 3434 assigned_to_me: bool | 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 limit: int | None = None, 3440 after_cursor: str | None = None, 3441 ) -> UserTaskReadyResponse: 3442 """ 3443 List an owner's ready tasks 3444 Returns open tasks with no unfinished blockers and no active session lease. 3445 Readiness is calculated by the server from the current task projection. It is 3446 a snapshot, not a reservation; claim a task lease before starting work. 3447 Results are ordered by priority (0, the most urgent, first), then oldest 3448 first, so the first page is always the most urgent ready work. 3449 Pass `explain=true` to include every open task with a stable readiness reason. 3450 3451 Args: 3452 user: User ID (`usr_...`) for user-scoped tasks. 3453 team: Team ID (`tem_...`) owning the tasks. 3454 org: Optional organization context for privileged callers. 3455 explain: Include blocked and actively leased open tasks with exclusion reasons. 3456 assigned_to_me: Only include tasks assigned to the authenticated user. 3457 source_scope: Only include tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 3458 source_type: Only include tasks whose source matches this object kind. 3459 source_id: Only include tasks whose source matches this object identity. 3460 epic: Only include tasks with this exact epic label. 3461 limit: Maximum number of readiness entries to return. Capped at 100. 3462 after_cursor: Opaque cursor returned by the previous page. 3463 3464 Returns: 3465 Successful response 3466 """ 3467 query: dict[str, object] = {} 3468 if team is not None: 3469 query["team"] = team 3470 if org is not None: 3471 query["org"] = org 3472 if explain is not None: 3473 query["explain"] = explain 3474 if assigned_to_me is not None: 3475 query["assigned_to_me"] = assigned_to_me 3476 if source_scope is not None: 3477 query["source_scope"] = source_scope 3478 if source_type is not None: 3479 query["source_type"] = source_type 3480 if source_id is not None: 3481 query["source_id"] = source_id 3482 if epic is not None: 3483 query["epic"] = epic 3484 if limit is not None: 3485 query["limit"] = limit 3486 if after_cursor is not None: 3487 query["after_cursor"] = after_cursor 3488 return await self._http.request( 3489 f"/api/v1/users/{user}/tasks/ready", 3490 query=query, 3491 response_type=UserTaskReadyResponse, 3492 ) 3493 3494 async def search( 3495 self, 3496 user: str, 3497 *, 3498 team: str | None = None, 3499 org: str | None = None, 3500 q: str | None = None, 3501 query: str | None = None, 3502 status: str | None = None, 3503 owner_user: str | None = None, 3504 owner_agent: str | None = None, 3505 priority: int | None = None, 3506 tag: str | None = None, 3507 parent: str | None = None, 3508 source_scope: str | None = None, 3509 source_type: str | None = None, 3510 source_id: str | None = None, 3511 epic: str | None = None, 3512 limit: int | None = None, 3513 after_cursor: str | None = None, 3514 ) -> UserTaskSearchResponse: 3515 """ 3516 Search an owner's tasks 3517 Performs a full-text search over tasks owned by the specified user or team and returns 3518 matching results. Combine `q` with the optional filters to narrow the result set 3519 further. When no query is provided, the endpoint behaves like a filtered list. 3520 The `query` field in the response echoes the effective search query. 3521 User-authenticated callers may search their personal tasks or tasks for teams 3522 they have joined. Privileged callers provide the owner in the route; the owner's 3523 organization is implied by that principal. An explicit `org` is optional and, 3524 when set, must match the owner's organization. 3525 3526 Args: 3527 user: User ID (`usr_...`) for user-scoped tasks. 3528 team: Team ID (`tem_...`). Only tasks belonging to this team are searched. 3529 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. 3530 q: Full-text search query matched against task names and descriptions. Takes precedence over `query` when both are provided. 3531 query: Alias for `q`. Use `q` when possible; this parameter exists for compatibility. 3532 status: Filter results by status. One of `"open"`, `"in_progress"`, `"in_review"`, or `"done"`. Omit to include all statuses. 3533 owner_user: Restrict results to tasks assigned to the user with this public ID (`usr_...`). 3534 owner_agent: Restrict results to tasks assigned to the agent with this public ID (`agi_...`). 3535 priority: Filter results by priority, from 0 (highest) to 4 (lowest). 3536 tag: Return only tasks carrying this tag (matched against the canonical lowercase form). 3537 parent: Return only subtasks of the given task (`tsk_...`), or pass `none` to return only top-level tasks. 3538 source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 3539 source_type: Return only tasks whose source matches this object kind. 3540 source_id: Return only tasks whose source matches this object identity. 3541 epic: Return only tasks with this exact epic label. 3542 limit: Maximum number of tasks to return. Capped at 100. 3543 after_cursor: Opaque cursor returned by the previous page. 3544 3545 Returns: 3546 Successful response 3547 """ 3548 query: dict[str, object] = {} 3549 if team is not None: 3550 query["team"] = team 3551 if org is not None: 3552 query["org"] = org 3553 if q is not None: 3554 query["q"] = q 3555 if query is not None: 3556 query["query"] = query 3557 if status is not None: 3558 query["status"] = status 3559 if owner_user is not None: 3560 query["owner_user"] = owner_user 3561 if owner_agent is not None: 3562 query["owner_agent"] = owner_agent 3563 if priority is not None: 3564 query["priority"] = priority 3565 if tag is not None: 3566 query["tag"] = tag 3567 if parent is not None: 3568 query["parent"] = parent 3569 if source_scope is not None: 3570 query["source_scope"] = source_scope 3571 if source_type is not None: 3572 query["source_type"] = source_type 3573 if source_id is not None: 3574 query["source_id"] = source_id 3575 if epic is not None: 3576 query["epic"] = epic 3577 if limit is not None: 3578 query["limit"] = limit 3579 if after_cursor is not None: 3580 query["after_cursor"] = after_cursor 3581 return await self._http.request( 3582 f"/api/v1/users/{user}/tasks/search", 3583 query=query, 3584 response_type=UserTaskSearchResponse, 3585 )
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, attention: bool | None = None, limit: int | None = None, after_cursor: str | None = None) -> UserTaskListResponse:
3210 async def list( 3211 self, 3212 user: str, 3213 *, 3214 team: str | None = None, 3215 org: str | None = None, 3216 status: str | None = None, 3217 owner_user: str | None = None, 3218 owner_agent: str | None = None, 3219 priority: int | None = None, 3220 tag: str | None = None, 3221 parent: str | None = None, 3222 source_scope: str | None = None, 3223 source_type: str | None = None, 3224 source_id: str | None = None, 3225 epic: str | None = None, 3226 search: str | None = None, 3227 sort: str | None = None, 3228 order: str | None = None, 3229 due_before: str | None = None, 3230 due_after: str | None = None, 3231 overdue: bool | None = None, 3232 ready: bool | None = None, 3233 attention: bool | None = None, 3234 limit: int | None = None, 3235 after_cursor: str | None = None, 3236 ) -> UserTaskListResponse: 3237 """ 3238 List an owner's tasks 3239 Returns tasks owned by the specified user or team. You can narrow results using the 3240 optional filters below. By default results are returned in reverse chronological 3241 order (most recently created first); use `sort` and `order` to sort by due date or 3242 priority instead. 3243 User-authenticated callers may list their personal tasks or tasks for teams they 3244 have joined. Privileged callers provide the owner in the route; the owner's 3245 organization is implied by that principal. An explicit `org` is optional and, 3246 when set, must match the owner's organization. 3247 3248 Args: 3249 user: User ID (`usr_...`) for user-scoped tasks. 3250 team: Team ID (`tem_...`). Only tasks belonging to this team are returned. 3251 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. 3252 status: Filter tasks by status. One of `"open"`, `"in_progress"`, `"in_review"`, or `"done"`. Omit to return tasks in all statuses. 3253 owner_user: Filter tasks assigned to a specific user. Provide the user's public ID (`usr_...`). 3254 owner_agent: Filter tasks assigned to a specific agent. Provide the agent's public ID (`agi_...`). 3255 priority: Filter tasks by priority, from 0 (highest) to 4 (lowest). 3256 tag: Return only tasks carrying this tag (matched against the canonical lowercase form). 3257 parent: Return only subtasks of the given task (`tsk_...`), or pass `none` to return only top-level tasks. 3258 source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 3259 source_type: Return only tasks whose source matches this object kind. Must be supplied with the other source filters. 3260 source_id: Return only tasks whose source matches this object identity. Must be supplied with the other source filters. 3261 epic: Return only tasks with this exact epic label. 3262 search: Restrict results to tasks whose name or description contains this string. 3263 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. 3264 order: Sort direction, `"asc"` or `"desc"`. Defaults to `"desc"` for `created` and `"asc"` for `due_date` and `priority`. 3265 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. 3266 due_after: Return only tasks with a due date strictly after this ISO 8601 datetime or date. Tasks without a due date are excluded. 3267 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. 3268 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. 3269 attention: When true, return paused, failed, or in-progress tasks with no lease or a past lease expiry. 3270 limit: Maximum number of tasks to return. Capped at 100. 3271 after_cursor: Opaque cursor returned by the previous page. 3272 3273 Returns: 3274 Successful response 3275 """ 3276 query: dict[str, object] = {} 3277 if team is not None: 3278 query["team"] = team 3279 if org is not None: 3280 query["org"] = org 3281 if status is not None: 3282 query["status"] = status 3283 if owner_user is not None: 3284 query["owner_user"] = owner_user 3285 if owner_agent is not None: 3286 query["owner_agent"] = owner_agent 3287 if priority is not None: 3288 query["priority"] = priority 3289 if tag is not None: 3290 query["tag"] = tag 3291 if parent is not None: 3292 query["parent"] = parent 3293 if source_scope is not None: 3294 query["source_scope"] = source_scope 3295 if source_type is not None: 3296 query["source_type"] = source_type 3297 if source_id is not None: 3298 query["source_id"] = source_id 3299 if epic is not None: 3300 query["epic"] = epic 3301 if search is not None: 3302 query["search"] = search 3303 if sort is not None: 3304 query["sort"] = sort 3305 if order is not None: 3306 query["order"] = order 3307 if due_before is not None: 3308 query["due_before"] = due_before 3309 if due_after is not None: 3310 query["due_after"] = due_after 3311 if overdue is not None: 3312 query["overdue"] = overdue 3313 if ready is not None: 3314 query["ready"] = ready 3315 if attention is not None: 3316 query["attention"] = attention 3317 if limit is not None: 3318 query["limit"] = limit 3319 if after_cursor is not None: 3320 query["after_cursor"] = after_cursor 3321 return await self._http.request( 3322 f"/api/v1/users/{user}/tasks", 3323 query=query, 3324 response_type=UserTaskListResponse, 3325 )
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","in_review", or"done". Omit to return tasks in all statuses. - owner_user: Filter tasks assigned to a specific user. Provide the user's public ID (
usr_...). - owner_agent: Filter tasks assigned to a specific agent. Provide the agent's public ID (
agi_...). - priority: Filter tasks by priority, from 0 (highest) to 4 (lowest).
- tag: Return only tasks carrying this tag (matched against the canonical lowercase form).
- parent: Return only subtasks of the given task (
tsk_...), or passnoneto return only top-level tasks. - source_scope: Return only tasks whose source matches this container. Must be supplied with
source_typeandsource_id. - source_type: Return only tasks whose source matches this object kind. Must be supplied with the other source filters.
- source_id: Return only tasks whose source matches this object identity. Must be supplied with the other source filters.
- epic: Return only tasks with this exact epic label.
- search: Restrict results to tasks whose name or description contains this string.
- sort: Sort key. One of
"created"(default most recently created first),"due_date"(soonest due first; tasks without a due date always sort last), or"priority"(most urgent first). Ties break by most recently created. - order: Sort direction,
"asc"or"desc". Defaults to"desc"forcreatedand"asc"fordue_dateandpriority. - due_before: Return only tasks with a due date strictly before this ISO 8601 datetime (
2026-08-01T00:00:00Z) or date (2026-08-01, meaning midnight UTC). Tasks without a due date are excluded. - due_after: Return only tasks with a due date strictly after this ISO 8601 datetime or date. Tasks without a due date are excluded.
- overdue: When
true, return only overdue tasks: a due date before the current UTC day and a status other than"done". A task due today is not overdue. - ready: When true, return only open tasks with no unfinished blockers and no active session lease. This is a projection snapshot; claim a lease before starting work.
- attention: When true, return paused, failed, or in-progress tasks with no lease or a past lease expiry.
- limit: Maximum number of tasks to return. Capped at 100.
- after_cursor: Opaque cursor returned by the previous page.
Returns:
Successful response
async def
create( self, user: str, input: UserTaskCreateInput) -> archastro.platform.types.tasks.Task:
3327 async def create(self, user: str, input: UserTaskCreateInput) -> Task: 3328 """ 3329 Create a task for an owner 3330 Creates a new task owned by the specified user or team and returns the full 3331 task object. User-authenticated calls are attributed to the authenticated 3332 user or agent. App-scoped developer and server-to-server callers must provide 3333 the task's explicit `org` scope and an explicit `user` or `agent` actor for 3334 team tasks; a user-owned task reuses the user in the route unless an explicit 3335 agent is supplied. Every referenced principal is validated against the app, 3336 owner, and team membership before creation. 3337 3338 Args: 3339 user: User ID (`usr_...`) for user-scoped tasks. 3340 input: Request body. 3341 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. 3342 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. 3343 input.task: Attributes for the task to create. `name` is required; all other fields are optional. 3344 input.team: Team ID (`tem_...`). The task will be owned by this team. 3345 3346 Returns: 3347 The newly created task. 3348 """ 3349 return await self._http.request( 3350 f"/api/v1/users/{user}/tasks", 3351 method="POST", 3352 body=input, 3353 response_type=Task, 3354 )
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:
3356 async def blocker_cycles( 3357 self, 3358 user: str, 3359 *, 3360 team: str | None = None, 3361 org: str | None = None, 3362 limit: int | None = None, 3363 after_cursor: str | None = None, 3364 ) -> UserTaskBlockerCyclesResponse: 3365 """ 3366 List task blocker cycles 3367 Runs an on-demand diagnostic over unfinished tasks owned by the specified 3368 team or user and returns a forward cursor-paginated page of complete cyclic 3369 blocker components. Detection is bounded to owners with at most 100 3370 unfinished tasks. This endpoint is read-only: cycles do not prevent task 3371 updates, lease acquisition, or completion. 3372 3373 Args: 3374 user: User ID (`usr_...`) for user-scoped tasks. 3375 team: Team ID (`tem_...`) owning the tasks. 3376 org: Optional organization context for privileged callers. 3377 limit: Maximum cycle components to return. Defaults to 50; maximum is 100. 3378 after_cursor: Opaque cursor returned by the preceding page. 3379 3380 Returns: 3381 Successful response 3382 """ 3383 query: dict[str, object] = {} 3384 if team is not None: 3385 query["team"] = team 3386 if org is not None: 3387 query["org"] = org 3388 if limit is not None: 3389 query["limit"] = limit 3390 if after_cursor is not None: 3391 query["after_cursor"] = after_cursor 3392 return await self._http.request( 3393 f"/api/v1/users/{user}/tasks/blocker_cycles", 3394 query=query, 3395 response_type=UserTaskBlockerCyclesResponse, 3396 )
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
by_source( self, user: str, input: UserTaskBySourceInput) -> archastro.platform.types.tasks.TaskEnsureResult:
3398 async def by_source(self, user: str, input: UserTaskBySourceInput) -> TaskEnsureResult: 3399 """ 3400 Find or create a task by source 3401 Atomically creates one task per owner, tenant and source. Retries return the current task without updating it. Historical tasks created through ordinary create are not adopted. 3402 3403 Args: 3404 user: User ID (`usr_...`) for user-scoped tasks. 3405 input: Request body. 3406 input.agent: Explicit acting agent for privileged callers. 3407 input.description: Initial task description. 3408 input.epic: Initial epic grouping. 3409 input.name: Initial task name. 3410 input.org: Explicit organization for privileged callers. 3411 input.source_id: Source identity, for example owner/repo#123. 3412 input.source_scope: Source scope, for example github. 3413 input.source_type: Source type, for example pull_request. 3414 input.status: Initial task status. 3415 input.team: Team owner. 3416 3417 Returns: 3418 The task and whether this request created it. 3419 """ 3420 return await self._http.request( 3421 f"/api/v1/users/{user}/tasks/by-source", 3422 method="PUT", 3423 body=input, 3424 response_type=TaskEnsureResult, 3425 )
Find or create a task by source Atomically creates one task per owner, tenant and source. Retries return the current task without updating it. Historical tasks created through ordinary create are not adopted.
Arguments:
- user: User ID (
usr_...) for user-scoped tasks. - input: Request body.
- input.agent: Explicit acting agent for privileged callers.
- input.description: Initial task description.
- input.epic: Initial epic grouping.
- input.name: Initial task name.
- input.org: Explicit organization for privileged callers.
- input.source_id: Source identity, for example owner/repo#123.
- input.source_scope: Source scope, for example github.
- input.source_type: Source type, for example pull_request.
- input.status: Initial task status.
- input.team: Team owner.
Returns:
The task and whether this request created it.
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:
3427 async def ready( 3428 self, 3429 user: str, 3430 *, 3431 team: str | None = None, 3432 org: str | None = None, 3433 explain: bool | None = None, 3434 assigned_to_me: bool | 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 limit: int | None = None, 3440 after_cursor: str | None = None, 3441 ) -> UserTaskReadyResponse: 3442 """ 3443 List an owner's ready tasks 3444 Returns open tasks with no unfinished blockers and no active session lease. 3445 Readiness is calculated by the server from the current task projection. It is 3446 a snapshot, not a reservation; claim a task lease before starting work. 3447 Results are ordered by priority (0, the most urgent, first), then oldest 3448 first, so the first page is always the most urgent ready work. 3449 Pass `explain=true` to include every open task with a stable readiness reason. 3450 3451 Args: 3452 user: User ID (`usr_...`) for user-scoped tasks. 3453 team: Team ID (`tem_...`) owning the tasks. 3454 org: Optional organization context for privileged callers. 3455 explain: Include blocked and actively leased open tasks with exclusion reasons. 3456 assigned_to_me: Only include tasks assigned to the authenticated user. 3457 source_scope: Only include tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 3458 source_type: Only include tasks whose source matches this object kind. 3459 source_id: Only include tasks whose source matches this object identity. 3460 epic: Only include tasks with this exact epic label. 3461 limit: Maximum number of readiness entries to return. Capped at 100. 3462 after_cursor: Opaque cursor returned by the previous page. 3463 3464 Returns: 3465 Successful response 3466 """ 3467 query: dict[str, object] = {} 3468 if team is not None: 3469 query["team"] = team 3470 if org is not None: 3471 query["org"] = org 3472 if explain is not None: 3473 query["explain"] = explain 3474 if assigned_to_me is not None: 3475 query["assigned_to_me"] = assigned_to_me 3476 if source_scope is not None: 3477 query["source_scope"] = source_scope 3478 if source_type is not None: 3479 query["source_type"] = source_type 3480 if source_id is not None: 3481 query["source_id"] = source_id 3482 if epic is not None: 3483 query["epic"] = epic 3484 if limit is not None: 3485 query["limit"] = limit 3486 if after_cursor is not None: 3487 query["after_cursor"] = after_cursor 3488 return await self._http.request( 3489 f"/api/v1/users/{user}/tasks/ready", 3490 query=query, 3491 response_type=UserTaskReadyResponse, 3492 )
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.
Results are ordered by priority (0, the most urgent, first), then oldest
first, so the first page is always the most urgent ready work.
Pass explain=true to include every open task with a stable readiness reason.
Arguments:
- 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:
3494 async def search( 3495 self, 3496 user: str, 3497 *, 3498 team: str | None = None, 3499 org: str | None = None, 3500 q: str | None = None, 3501 query: str | None = None, 3502 status: str | None = None, 3503 owner_user: str | None = None, 3504 owner_agent: str | None = None, 3505 priority: int | None = None, 3506 tag: str | None = None, 3507 parent: str | None = None, 3508 source_scope: str | None = None, 3509 source_type: str | None = None, 3510 source_id: str | None = None, 3511 epic: str | None = None, 3512 limit: int | None = None, 3513 after_cursor: str | None = None, 3514 ) -> UserTaskSearchResponse: 3515 """ 3516 Search an owner's tasks 3517 Performs a full-text search over tasks owned by the specified user or team and returns 3518 matching results. Combine `q` with the optional filters to narrow the result set 3519 further. When no query is provided, the endpoint behaves like a filtered list. 3520 The `query` field in the response echoes the effective search query. 3521 User-authenticated callers may search their personal tasks or tasks for teams 3522 they have joined. Privileged callers provide the owner in the route; the owner's 3523 organization is implied by that principal. An explicit `org` is optional and, 3524 when set, must match the owner's organization. 3525 3526 Args: 3527 user: User ID (`usr_...`) for user-scoped tasks. 3528 team: Team ID (`tem_...`). Only tasks belonging to this team are searched. 3529 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. 3530 q: Full-text search query matched against task names and descriptions. Takes precedence over `query` when both are provided. 3531 query: Alias for `q`. Use `q` when possible; this parameter exists for compatibility. 3532 status: Filter results by status. One of `"open"`, `"in_progress"`, `"in_review"`, or `"done"`. Omit to include all statuses. 3533 owner_user: Restrict results to tasks assigned to the user with this public ID (`usr_...`). 3534 owner_agent: Restrict results to tasks assigned to the agent with this public ID (`agi_...`). 3535 priority: Filter results by priority, from 0 (highest) to 4 (lowest). 3536 tag: Return only tasks carrying this tag (matched against the canonical lowercase form). 3537 parent: Return only subtasks of the given task (`tsk_...`), or pass `none` to return only top-level tasks. 3538 source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 3539 source_type: Return only tasks whose source matches this object kind. 3540 source_id: Return only tasks whose source matches this object identity. 3541 epic: Return only tasks with this exact epic label. 3542 limit: Maximum number of tasks to return. Capped at 100. 3543 after_cursor: Opaque cursor returned by the previous page. 3544 3545 Returns: 3546 Successful response 3547 """ 3548 query: dict[str, object] = {} 3549 if team is not None: 3550 query["team"] = team 3551 if org is not None: 3552 query["org"] = org 3553 if q is not None: 3554 query["q"] = q 3555 if query is not None: 3556 query["query"] = query 3557 if status is not None: 3558 query["status"] = status 3559 if owner_user is not None: 3560 query["owner_user"] = owner_user 3561 if owner_agent is not None: 3562 query["owner_agent"] = owner_agent 3563 if priority is not None: 3564 query["priority"] = priority 3565 if tag is not None: 3566 query["tag"] = tag 3567 if parent is not None: 3568 query["parent"] = parent 3569 if source_scope is not None: 3570 query["source_scope"] = source_scope 3571 if source_type is not None: 3572 query["source_type"] = source_type 3573 if source_id is not None: 3574 query["source_id"] = source_id 3575 if epic is not None: 3576 query["epic"] = epic 3577 if limit is not None: 3578 query["limit"] = limit 3579 if after_cursor is not None: 3580 query["after_cursor"] = after_cursor 3581 return await self._http.request( 3582 f"/api/v1/users/{user}/tasks/search", 3583 query=query, 3584 response_type=UserTaskSearchResponse, 3585 )
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","in_review", 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:
3588class AsyncUserThreadResource: 3589 def __init__(self, http: HttpClient): 3590 self._http = http 3591 3592 async def list( 3593 self, 3594 user: str, 3595 *, 3596 agent: builtins.list[str] | None = None, 3597 filter: builtins.list[dict[str, Any]] | None = None, 3598 ) -> UserThreadListResponse: 3599 """ 3600 List threads for a user 3601 Returns all threads visible to the specified user. The authenticated caller must 3602 have access to the target user's account; a 403 is returned otherwise. 3603 Pass one or more `agent` IDs to narrow results to threads where at least one of 3604 the listed agents is also a member useful for displaying every thread a user 3605 shares with a particular agent. Pass one or more `filter` objects to narrow 3606 results by thread metadata key/value pairs. Both narrowings may be combined in 3607 a single request. 3608 Results are returned as a flat array; no cursor-based pagination is applied. 3609 Threads are ordered with default threads first, then by most recent activity 3610 (newest first), each carrying a `last_activity` timestamp. 3611 3612 Args: 3613 user: User ID (`usr_...`) whose threads should be listed. 3614 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. 3615 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. 3616 3617 Returns: 3618 Successful response 3619 """ 3620 query: dict[str, object] = {} 3621 if agent is not None: 3622 query["agent"] = agent 3623 if filter is not None: 3624 query["filter"] = filter 3625 return await self._http.request( 3626 f"/api/v1/users/{user}/threads", 3627 query=query, 3628 response_type=UserThreadListResponse, 3629 ) 3630 3631 async def create(self, user: str, input: UserThreadCreateInput) -> Thread: 3632 """ 3633 Create a thread for a user 3634 Creates a new thread owned by the specified user. The authenticated caller must 3635 have access to the target user's account; a 403 is returned otherwise. 3636 An automatic welcome message is sent into the thread upon creation unless 3637 `skip_welcome_message` is set to `true`. The thread is immediately visible to 3638 the owning user and any members added at creation time. 3639 3640 Args: 3641 user: User ID (`usr_...`) whose threads should be listed. 3642 input: Request body. 3643 input.skip_welcome_message: When `true`, suppresses the automatic welcome message that is otherwise sent into the thread on creation. Defaults to `false`. 3644 input.thread: Attributes for the new thread. See ThreadCreateParams for the full set of accepted fields. 3645 3646 Returns: 3647 The newly created thread object. 3648 """ 3649 return await self._http.request( 3650 f"/api/v1/users/{user}/threads", 3651 method="POST", 3652 body=input, 3653 response_type=Thread, 3654 )
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:
3592 async def list( 3593 self, 3594 user: str, 3595 *, 3596 agent: builtins.list[str] | None = None, 3597 filter: builtins.list[dict[str, Any]] | None = None, 3598 ) -> UserThreadListResponse: 3599 """ 3600 List threads for a user 3601 Returns all threads visible to the specified user. The authenticated caller must 3602 have access to the target user's account; a 403 is returned otherwise. 3603 Pass one or more `agent` IDs to narrow results to threads where at least one of 3604 the listed agents is also a member useful for displaying every thread a user 3605 shares with a particular agent. Pass one or more `filter` objects to narrow 3606 results by thread metadata key/value pairs. Both narrowings may be combined in 3607 a single request. 3608 Results are returned as a flat array; no cursor-based pagination is applied. 3609 Threads are ordered with default threads first, then by most recent activity 3610 (newest first), each carrying a `last_activity` timestamp. 3611 3612 Args: 3613 user: User ID (`usr_...`) whose threads should be listed. 3614 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. 3615 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. 3616 3617 Returns: 3618 Successful response 3619 """ 3620 query: dict[str, object] = {} 3621 if agent is not None: 3622 query["agent"] = agent 3623 if filter is not None: 3624 query["filter"] = filter 3625 return await self._http.request( 3626 f"/api/v1/users/{user}/threads", 3627 query=query, 3628 response_type=UserThreadListResponse, 3629 )
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:
3631 async def create(self, user: str, input: UserThreadCreateInput) -> Thread: 3632 """ 3633 Create a thread for a user 3634 Creates a new thread owned by the specified user. The authenticated caller must 3635 have access to the target user's account; a 403 is returned otherwise. 3636 An automatic welcome message is sent into the thread upon creation unless 3637 `skip_welcome_message` is set to `true`. The thread is immediately visible to 3638 the owning user and any members added at creation time. 3639 3640 Args: 3641 user: User ID (`usr_...`) whose threads should be listed. 3642 input: Request body. 3643 input.skip_welcome_message: When `true`, suppresses the automatic welcome message that is otherwise sent into the thread on creation. Defaults to `false`. 3644 input.thread: Attributes for the new thread. See ThreadCreateParams for the full set of accepted fields. 3645 3646 Returns: 3647 The newly created thread object. 3648 """ 3649 return await self._http.request( 3650 f"/api/v1/users/{user}/threads", 3651 method="POST", 3652 body=input, 3653 response_type=Thread, 3654 )
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:
3657class AsyncTokenResource: 3658 def __init__(self, http: HttpClient): 3659 self._http = http 3660 3661 async def list(self, user: str) -> TokenListResponse: 3662 """ 3663 List personal access tokens 3664 Returns all access tokens associated with the authenticated user, including 3665 active and revoked tokens. Tokens are returned without their raw JWT values 3666 the plaintext JWT is only available at creation time. 3667 The caller must be the user identified by `user` and must present a 3668 first-party session (or a `full_access` access token). 3669 3670 Args: 3671 user: User ID (`usr_...`) or `me` for the authenticated user. 3672 3673 Returns: 3674 Successful response 3675 """ 3676 return await self._http.request( 3677 f"/api/v1/users/{user}/tokens", 3678 response_type=TokenListResponse, 3679 ) 3680 3681 async def create(self, user: str, input: TokenCreateInput) -> SystemAccessToken: 3682 """ 3683 Create a personal access token 3684 Issues a new long-lived access token for the authenticated user. The raw 3685 JWT is returned in the `token` field of the response exactly once and 3686 cannot be retrieved again store it securely immediately after creation. 3687 `scopes` is optional. When omitted the token receives `full_access`. 3688 Known catalog scopes (for example `profile`) restrict the token through 3689 the same `ScopeGuard` used by OAuth. 3690 `expires_in_days` is optional and must be one of `7`, `30`, `60`, `90`, 3691 or `365`. When omitted the token lasts 30 days. Each user may hold at 3692 most 50 active tokens; exceeding that limit returns 429. 3693 The caller must be the user identified by `user` and must present a 3694 first-party session (or a `full_access` access token). A restricted 3695 access token cannot mint another token. 3696 3697 Args: 3698 user: User ID (`usr_...`) or `me` for the authenticated user. 3699 input: Request body. 3700 input.expires_in_days: Lifetime in days. One of `7`, `30`, `60`, `90`, or `365`. Defaults to `30`. 3701 input.name: Human-readable label for the token (e.g. `"Codex MCP"`). Stored as metadata only. 3702 input.scopes: Optional OAuth scopes to stamp on the token. Omit for `full_access`. 3703 3704 Returns: 3705 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. 3706 """ 3707 return await self._http.request( 3708 f"/api/v1/users/{user}/tokens", 3709 method="POST", 3710 body=input, 3711 response_type=SystemAccessToken, 3712 ) 3713 3714 async def delete(self, user: str, token: str) -> SystemAccessToken: 3715 """ 3716 Revoke a personal access token 3717 Permanently revokes the specified access token belonging to the 3718 authenticated user. Once revoked, the token is immediately rejected by 3719 all API endpoints and cannot be reinstated. The token record is retained 3720 and returned in the response with `revoked_at` populated. 3721 The caller must be the user identified by `user` and must present a 3722 first-party session (or a `full_access` access token). Returns 404 if 3723 the token does not exist or does not belong to the caller. 3724 3725 Args: 3726 user: User ID (`usr_...`) or `me` for the authenticated user. 3727 token: Access token ID (`sat_...`). Must belong to the authenticated user. 3728 3729 Returns: 3730 The revoked access token. The `revoked_at` field is populated with the time of revocation. 3731 """ 3732 return await self._http.request( 3733 f"/api/v1/users/{user}/tokens/{token}", 3734 method="DELETE", 3735 response_type=SystemAccessToken, 3736 )
AsyncTokenResource(http: archastro.platform.runtime.http_client.HttpClient)
3661 async def list(self, user: str) -> TokenListResponse: 3662 """ 3663 List personal access tokens 3664 Returns all access tokens associated with the authenticated user, including 3665 active and revoked tokens. Tokens are returned without their raw JWT values 3666 the plaintext JWT is only available at creation time. 3667 The caller must be the user identified by `user` and must present a 3668 first-party session (or a `full_access` access token). 3669 3670 Args: 3671 user: User ID (`usr_...`) or `me` for the authenticated user. 3672 3673 Returns: 3674 Successful response 3675 """ 3676 return await self._http.request( 3677 f"/api/v1/users/{user}/tokens", 3678 response_type=TokenListResponse, 3679 )
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:
3681 async def create(self, user: str, input: TokenCreateInput) -> SystemAccessToken: 3682 """ 3683 Create a personal access token 3684 Issues a new long-lived access token for the authenticated user. The raw 3685 JWT is returned in the `token` field of the response exactly once and 3686 cannot be retrieved again store it securely immediately after creation. 3687 `scopes` is optional. When omitted the token receives `full_access`. 3688 Known catalog scopes (for example `profile`) restrict the token through 3689 the same `ScopeGuard` used by OAuth. 3690 `expires_in_days` is optional and must be one of `7`, `30`, `60`, `90`, 3691 or `365`. When omitted the token lasts 30 days. Each user may hold at 3692 most 50 active tokens; exceeding that limit returns 429. 3693 The caller must be the user identified by `user` and must present a 3694 first-party session (or a `full_access` access token). A restricted 3695 access token cannot mint another token. 3696 3697 Args: 3698 user: User ID (`usr_...`) or `me` for the authenticated user. 3699 input: Request body. 3700 input.expires_in_days: Lifetime in days. One of `7`, `30`, `60`, `90`, or `365`. Defaults to `30`. 3701 input.name: Human-readable label for the token (e.g. `"Codex MCP"`). Stored as metadata only. 3702 input.scopes: Optional OAuth scopes to stamp on the token. Omit for `full_access`. 3703 3704 Returns: 3705 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. 3706 """ 3707 return await self._http.request( 3708 f"/api/v1/users/{user}/tokens", 3709 method="POST", 3710 body=input, 3711 response_type=SystemAccessToken, 3712 )
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:
3714 async def delete(self, user: str, token: str) -> SystemAccessToken: 3715 """ 3716 Revoke a personal access token 3717 Permanently revokes the specified access token belonging to the 3718 authenticated user. Once revoked, the token is immediately rejected by 3719 all API endpoints and cannot be reinstated. The token record is retained 3720 and returned in the response with `revoked_at` populated. 3721 The caller must be the user identified by `user` and must present a 3722 first-party session (or a `full_access` access token). Returns 404 if 3723 the token does not exist or does not belong to the caller. 3724 3725 Args: 3726 user: User ID (`usr_...`) or `me` for the authenticated user. 3727 token: Access token ID (`sat_...`). Must belong to the authenticated user. 3728 3729 Returns: 3730 The revoked access token. The `revoked_at` field is populated with the time of revocation. 3731 """ 3732 return await self._http.request( 3733 f"/api/v1/users/{user}/tokens/{token}", 3734 method="DELETE", 3735 response_type=SystemAccessToken, 3736 )
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:
3739class AsyncUserResource: 3740 def __init__(self, http: HttpClient): 3741 self._http = http 3742 self.integrations = AsyncIntegrationResource(http) 3743 self.ssh_keys = AsyncUserSshKeyResource(http) 3744 self.tasks = AsyncUserTaskResource(http) 3745 self.threads = AsyncUserThreadResource(http) 3746 self.tokens = AsyncTokenResource(http) 3747 3748 async def me(self, *, entitlement: list[str] | None = None) -> CurrentUser: 3749 """ 3750 Retrieve the current user 3751 Returns the user associated with the authenticated session or bearer 3752 token. This is the canonical way to resolve "who am I?" after 3753 authentication. 3754 The response includes the user's profile, notification settings, and 3755 profile picture, along with the app, organization, and sandbox the 3756 token is scoped to and their display names enough to establish full 3757 session context in a single call. Unauthenticated requests return 401. 3758 3759 Args: 3760 entitlement: Entitlement catalog keys to evaluate. Supplying this expansion additionally requires `entitlements:read`. 3761 3762 Returns: 3763 The authenticated user object. 3764 """ 3765 query: dict[str, object] = {} 3766 if entitlement is not None: 3767 query["entitlement"] = entitlement 3768 return await self._http.request("/api/v1/users/me", query=query, response_type=CurrentUser) 3769 3770 async def get(self, user: str) -> User: 3771 """ 3772 Retrieve a user by ID 3773 Returns the user identified by `user`. The authenticated user must share 3774 an organization or at least one team with the target user; other requests 3775 are rejected with 403. 3776 A user may always retrieve their own profile with this endpoint. Use the 3777 `GET /users/me` endpoint as a convenience alias for retrieving the 3778 authenticated user without specifying an ID. 3779 3780 Args: 3781 user: User ID (`usr_...`) of the user to retrieve. 3782 3783 Returns: 3784 The requested user object. 3785 """ 3786 return await self._http.request(f"/api/v1/users/{user}", response_type=User) 3787 3788 async def artifacts( 3789 self, user: str, *, group_key: str | None = None, group_key_prefix: str | None = None 3790 ) -> UserArtifactsResponse: 3791 """ 3792 List a user's artifacts 3793 Returns all artifacts owned by the specified user. Artifacts represent 3794 AI-generated or user-uploaded files associated with agent sessions, 3795 threads, or sandboxes such as images, documents, and code outputs. 3796 The authenticated user must be requesting their own artifacts or must 3797 have administrative access. Attempting to list artifacts for a user 3798 the caller is not authorized to access returns 403. 3799 Results are returned in a single page without cursor pagination. Each 3800 artifact in the response reflects the state of its current version, 3801 including a short-lived signed `file_url` for direct download. 3802 3803 Args: 3804 user: User ID (`usr_...`). The authenticated user must be this user or have access to their artifacts. 3805 group_key: Case-sensitive exact group key. Mutually exclusive with group_key_prefix; null keys do not match. 3806 group_key_prefix: Nonempty case-sensitive literal prefix (percent, underscore and backslash are literal). Mutually exclusive with group_key. 3807 3808 Returns: 3809 Successful response 3810 """ 3811 query: dict[str, object] = {} 3812 if group_key is not None: 3813 query["group_key"] = group_key 3814 if group_key_prefix is not None: 3815 query["group_key_prefix"] = group_key_prefix 3816 return await self._http.request( 3817 f"/api/v1/users/{user}/artifacts", 3818 query=query, 3819 response_type=UserArtifactsResponse, 3820 ) 3821 3822 async def invites(self, user: str, input: UserInvitesInput) -> UserInvite: 3823 """ 3824 Create a user invite 3825 Creates a new invite for the authenticated user. The invite can optionally be 3826 scoped to a specific thread, a persona, or carry arbitrary metadata. The 3827 caller receives the new invite object at HTTP 201. 3828 The invite key is always generated server-side (192-bit URL-safe random 3829 string) and cannot be supplied by the caller. 3830 The path `:user` must match the authenticated user. If a `thread_id` is 3831 provided, the authenticated user must have permission to invite others to that 3832 thread; team threads are not supported and return an error. Supplying a 3833 `thread_id` that does not exist or that belongs to a different user returns 3834 an error. If a key collision occurs during creation the call returns a 409 3835 conflict simply retry to generate a new key. 3836 3837 Args: 3838 user: User ID (`usr_...`). Must match the authenticated user. 3839 input: Request body. 3840 input.invite: Parameters for the new invite. See the UserInviteCreateParams schema for field details. 3841 3842 Returns: 3843 The newly created invite object. 3844 """ 3845 return await self._http.request( 3846 f"/api/v1/users/{user}/invites", 3847 method="POST", 3848 body=input, 3849 response_type=UserInvite, 3850 ) 3851 3852 async def orgs(self, user: str) -> UserOrgsResponse: 3853 """ 3854 List organizations for a user 3855 Returns the organizations the specified user belongs to. A user can belong 3856 to at most one organization, so the `data` array contains either zero or one 3857 items. 3858 The authenticated viewer must have permission to inspect the target user. 3859 Returns an empty `data` array when the user has no organization membership. 3860 3861 Args: 3862 user: User ID (`usr_...`) whose organization membership you want to retrieve. 3863 3864 Returns: 3865 Successful response 3866 """ 3867 return await self._http.request( 3868 f"/api/v1/users/{user}/orgs", 3869 response_type=UserOrgsResponse, 3870 ) 3871 3872 async def profile(self, user: str, input: UserProfileInput) -> User: 3873 """ 3874 Update the current user's profile 3875 Updates one or more profile fields for the authenticated user. All 3876 fields are optional; omit any you do not want to change. 3877 When `profile_picture` is supplied, the image is uploaded and replaces 3878 the existing picture. The previous picture is deleted after the new one 3879 is stored. Image upload failures return 422 without modifying other 3880 profile fields. 3881 3882 Args: 3883 user: User ID (`usr_...`) or `"me"` for the authenticated user. 3884 input: Request body. 3885 input.alias: Short display alias shown in place of the full name in compact UI contexts. 3886 input.clear_full_name: Set to true to clear the optional display name. Cannot be combined with full_name. 3887 input.clear_profile_picture: Set to true to remove the current profile picture. Cannot be combined with profile_picture. 3888 input.full_name: Updated display name for the user. 3889 input.metadata: Arbitrary key-value metadata to associate with the user. Existing keys are merged; pass `null` for a key to remove it. 3890 input.profile_picture: New profile picture to upload as a base64-encoded image. Replaces any existing picture. 3891 3892 Returns: 3893 The user object with updated profile fields. 3894 """ 3895 return await self._http.request( 3896 f"/api/v1/users/{user}/profile", 3897 method="PUT", 3898 body=input, 3899 response_type=User, 3900 ) 3901 3902 async def task_epics( 3903 self, 3904 user: str, 3905 *, 3906 team: str | None = None, 3907 org: str | None = None, 3908 source_scope: str | None = None, 3909 source_type: str | None = None, 3910 source_id: str | None = None, 3911 top_priority: int | None = None, 3912 include_closed: bool | None = None, 3913 limit: int | None = None, 3914 after_cursor: str | None = None, 3915 ) -> UserTaskEpicsResponse: 3916 """ 3917 List an owner's epic summaries 3918 Groups tasks by their exact epic label, ordered by label. Closed tasks include cancelled tasks, but cancelled prerequisites still block. Source filters select the tasks summarized; blockers outside that selection still affect readiness. Root ranking is capped per epic and root_blockers_partial is true when that graph is truncated. No epic entity is created. 3919 3920 Args: 3921 source_scope: Exact source scope; supply all three source fields. 3922 source_type: Exact source type. 3923 source_id: Exact source ID. 3924 top_priority: Exact highest open priority, from 0 to 4. 3925 include_closed: Include epics with no non-closed tasks; defaults to false. 3926 limit: Maximum epics; defaults to 50, capped at 100. 3927 after_cursor: Opaque forward cursor from the preceding page. 3928 3929 Returns: 3930 Successful response 3931 """ 3932 query: dict[str, object] = {} 3933 if team is not None: 3934 query["team"] = team 3935 if org is not None: 3936 query["org"] = org 3937 if source_scope is not None: 3938 query["source_scope"] = source_scope 3939 if source_type is not None: 3940 query["source_type"] = source_type 3941 if source_id is not None: 3942 query["source_id"] = source_id 3943 if top_priority is not None: 3944 query["top_priority"] = top_priority 3945 if include_closed is not None: 3946 query["include_closed"] = include_closed 3947 if limit is not None: 3948 query["limit"] = limit 3949 if after_cursor is not None: 3950 query["after_cursor"] = after_cursor 3951 return await self._http.request( 3952 f"/api/v1/users/{user}/task_epics", 3953 query=query, 3954 response_type=UserTaskEpicsResponse, 3955 )
AsyncUserResource(http: archastro.platform.runtime.http_client.HttpClient)
3740 def __init__(self, http: HttpClient): 3741 self._http = http 3742 self.integrations = AsyncIntegrationResource(http) 3743 self.ssh_keys = AsyncUserSshKeyResource(http) 3744 self.tasks = AsyncUserTaskResource(http) 3745 self.threads = AsyncUserThreadResource(http) 3746 self.tokens = AsyncTokenResource(http)
async def
me( self, *, entitlement: list[str] | None = None) -> archastro.platform.types.common.CurrentUser:
3748 async def me(self, *, entitlement: list[str] | None = None) -> CurrentUser: 3749 """ 3750 Retrieve the current user 3751 Returns the user associated with the authenticated session or bearer 3752 token. This is the canonical way to resolve "who am I?" after 3753 authentication. 3754 The response includes the user's profile, notification settings, and 3755 profile picture, along with the app, organization, and sandbox the 3756 token is scoped to and their display names enough to establish full 3757 session context in a single call. Unauthenticated requests return 401. 3758 3759 Args: 3760 entitlement: Entitlement catalog keys to evaluate. Supplying this expansion additionally requires `entitlements:read`. 3761 3762 Returns: 3763 The authenticated user object. 3764 """ 3765 query: dict[str, object] = {} 3766 if entitlement is not None: 3767 query["entitlement"] = entitlement 3768 return await self._http.request("/api/v1/users/me", query=query, response_type=CurrentUser)
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.
Arguments:
- entitlement: Entitlement catalog keys to evaluate. Supplying this expansion additionally requires
entitlements:read.
Returns:
The authenticated user object.
3770 async def get(self, user: str) -> User: 3771 """ 3772 Retrieve a user by ID 3773 Returns the user identified by `user`. The authenticated user must share 3774 an organization or at least one team with the target user; other requests 3775 are rejected with 403. 3776 A user may always retrieve their own profile with this endpoint. Use the 3777 `GET /users/me` endpoint as a convenience alias for retrieving the 3778 authenticated user without specifying an ID. 3779 3780 Args: 3781 user: User ID (`usr_...`) of the user to retrieve. 3782 3783 Returns: 3784 The requested user object. 3785 """ 3786 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
an organization or at least one team with the target user; other requests
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.
async def
artifacts( self, user: str, *, group_key: str | None = None, group_key_prefix: str | None = None) -> UserArtifactsResponse:
3788 async def artifacts( 3789 self, user: str, *, group_key: str | None = None, group_key_prefix: str | None = None 3790 ) -> UserArtifactsResponse: 3791 """ 3792 List a user's artifacts 3793 Returns all artifacts owned by the specified user. Artifacts represent 3794 AI-generated or user-uploaded files associated with agent sessions, 3795 threads, or sandboxes such as images, documents, and code outputs. 3796 The authenticated user must be requesting their own artifacts or must 3797 have administrative access. Attempting to list artifacts for a user 3798 the caller is not authorized to access returns 403. 3799 Results are returned in a single page without cursor pagination. Each 3800 artifact in the response reflects the state of its current version, 3801 including a short-lived signed `file_url` for direct download. 3802 3803 Args: 3804 user: User ID (`usr_...`). The authenticated user must be this user or have access to their artifacts. 3805 group_key: Case-sensitive exact group key. Mutually exclusive with group_key_prefix; null keys do not match. 3806 group_key_prefix: Nonempty case-sensitive literal prefix (percent, underscore and backslash are literal). Mutually exclusive with group_key. 3807 3808 Returns: 3809 Successful response 3810 """ 3811 query: dict[str, object] = {} 3812 if group_key is not None: 3813 query["group_key"] = group_key 3814 if group_key_prefix is not None: 3815 query["group_key_prefix"] = group_key_prefix 3816 return await self._http.request( 3817 f"/api/v1/users/{user}/artifacts", 3818 query=query, 3819 response_type=UserArtifactsResponse, 3820 )
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. - group_key: Case-sensitive exact group key. Mutually exclusive with group_key_prefix; null keys do not match.
- group_key_prefix: Nonempty case-sensitive literal prefix (percent, underscore and backslash are literal). Mutually exclusive with group_key.
Returns:
Successful response
async def
invites( self, user: str, input: UserInvitesInput) -> archastro.platform.types.users.UserInvite:
3822 async def invites(self, user: str, input: UserInvitesInput) -> UserInvite: 3823 """ 3824 Create a user invite 3825 Creates a new invite for the authenticated user. The invite can optionally be 3826 scoped to a specific thread, a persona, or carry arbitrary metadata. The 3827 caller receives the new invite object at HTTP 201. 3828 The invite key is always generated server-side (192-bit URL-safe random 3829 string) and cannot be supplied by the caller. 3830 The path `:user` must match the authenticated user. If a `thread_id` is 3831 provided, the authenticated user must have permission to invite others to that 3832 thread; team threads are not supported and return an error. Supplying a 3833 `thread_id` that does not exist or that belongs to a different user returns 3834 an error. If a key collision occurs during creation the call returns a 409 3835 conflict simply retry to generate a new key. 3836 3837 Args: 3838 user: User ID (`usr_...`). Must match the authenticated user. 3839 input: Request body. 3840 input.invite: Parameters for the new invite. See the UserInviteCreateParams schema for field details. 3841 3842 Returns: 3843 The newly created invite object. 3844 """ 3845 return await self._http.request( 3846 f"/api/v1/users/{user}/invites", 3847 method="POST", 3848 body=input, 3849 response_type=UserInvite, 3850 )
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.
3852 async def orgs(self, user: str) -> UserOrgsResponse: 3853 """ 3854 List organizations for a user 3855 Returns the organizations the specified user belongs to. A user can belong 3856 to at most one organization, so the `data` array contains either zero or one 3857 items. 3858 The authenticated viewer must have permission to inspect the target user. 3859 Returns an empty `data` array when the user has no organization membership. 3860 3861 Args: 3862 user: User ID (`usr_...`) whose organization membership you want to retrieve. 3863 3864 Returns: 3865 Successful response 3866 """ 3867 return await self._http.request( 3868 f"/api/v1/users/{user}/orgs", 3869 response_type=UserOrgsResponse, 3870 )
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:
3872 async def profile(self, user: str, input: UserProfileInput) -> User: 3873 """ 3874 Update the current user's profile 3875 Updates one or more profile fields for the authenticated user. All 3876 fields are optional; omit any you do not want to change. 3877 When `profile_picture` is supplied, the image is uploaded and replaces 3878 the existing picture. The previous picture is deleted after the new one 3879 is stored. Image upload failures return 422 without modifying other 3880 profile fields. 3881 3882 Args: 3883 user: User ID (`usr_...`) or `"me"` for the authenticated user. 3884 input: Request body. 3885 input.alias: Short display alias shown in place of the full name in compact UI contexts. 3886 input.clear_full_name: Set to true to clear the optional display name. Cannot be combined with full_name. 3887 input.clear_profile_picture: Set to true to remove the current profile picture. Cannot be combined with profile_picture. 3888 input.full_name: Updated display name for the user. 3889 input.metadata: Arbitrary key-value metadata to associate with the user. Existing keys are merged; pass `null` for a key to remove it. 3890 input.profile_picture: New profile picture to upload as a base64-encoded image. Replaces any existing picture. 3891 3892 Returns: 3893 The user object with updated profile fields. 3894 """ 3895 return await self._http.request( 3896 f"/api/v1/users/{user}/profile", 3897 method="PUT", 3898 body=input, 3899 response_type=User, 3900 )
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.clear_full_name: Set to true to clear the optional display name. Cannot be combined with full_name.
- input.clear_profile_picture: Set to true to remove the current profile picture. Cannot be combined with profile_picture.
- 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.
async def
task_epics( self, user: str, *, team: str | None = None, org: str | None = None, source_scope: str | None = None, source_type: str | None = None, source_id: str | None = None, top_priority: int | None = None, include_closed: bool | None = None, limit: int | None = None, after_cursor: str | None = None) -> UserTaskEpicsResponse:
3902 async def task_epics( 3903 self, 3904 user: str, 3905 *, 3906 team: str | None = None, 3907 org: str | None = None, 3908 source_scope: str | None = None, 3909 source_type: str | None = None, 3910 source_id: str | None = None, 3911 top_priority: int | None = None, 3912 include_closed: bool | None = None, 3913 limit: int | None = None, 3914 after_cursor: str | None = None, 3915 ) -> UserTaskEpicsResponse: 3916 """ 3917 List an owner's epic summaries 3918 Groups tasks by their exact epic label, ordered by label. Closed tasks include cancelled tasks, but cancelled prerequisites still block. Source filters select the tasks summarized; blockers outside that selection still affect readiness. Root ranking is capped per epic and root_blockers_partial is true when that graph is truncated. No epic entity is created. 3919 3920 Args: 3921 source_scope: Exact source scope; supply all three source fields. 3922 source_type: Exact source type. 3923 source_id: Exact source ID. 3924 top_priority: Exact highest open priority, from 0 to 4. 3925 include_closed: Include epics with no non-closed tasks; defaults to false. 3926 limit: Maximum epics; defaults to 50, capped at 100. 3927 after_cursor: Opaque forward cursor from the preceding page. 3928 3929 Returns: 3930 Successful response 3931 """ 3932 query: dict[str, object] = {} 3933 if team is not None: 3934 query["team"] = team 3935 if org is not None: 3936 query["org"] = org 3937 if source_scope is not None: 3938 query["source_scope"] = source_scope 3939 if source_type is not None: 3940 query["source_type"] = source_type 3941 if source_id is not None: 3942 query["source_id"] = source_id 3943 if top_priority is not None: 3944 query["top_priority"] = top_priority 3945 if include_closed is not None: 3946 query["include_closed"] = include_closed 3947 if limit is not None: 3948 query["limit"] = limit 3949 if after_cursor is not None: 3950 query["after_cursor"] = after_cursor 3951 return await self._http.request( 3952 f"/api/v1/users/{user}/task_epics", 3953 query=query, 3954 response_type=UserTaskEpicsResponse, 3955 )
List an owner's epic summaries Groups tasks by their exact epic label, ordered by label. Closed tasks include cancelled tasks, but cancelled prerequisites still block. Source filters select the tasks summarized; blockers outside that selection still affect readiness. Root ranking is capped per epic and root_blockers_partial is true when that graph is truncated. No epic entity is created.
Arguments:
- source_scope: Exact source scope; supply all three source fields.
- source_type: Exact source type.
- source_id: Exact source ID.
- top_priority: Exact highest open priority, from 0 to 4.
- include_closed: Include epics with no non-closed tasks; defaults to false.
- limit: Maximum epics; defaults to 50, capped at 100.
- after_cursor: Opaque forward cursor from the preceding page.
Returns:
Successful response
class
IntegrationResource:
3958class IntegrationResource: 3959 def __init__(self, http: SyncHttpClient): 3960 self._http = http 3961 3962 def access_token(self, user: str, provider: str) -> IntegrationAccessTokenResponse: 3963 """ 3964 Retrieve a GitHub integration access token 3965 Returns a valid GitHub access token for one integration owned by the 3966 authenticated user. Expired tokens are refreshed before the response is 3967 returned. 3968 This endpoint accepts the user's own bearer token, or the app's secret key 3969 acting server-to-server for one of its users. Developer, agent, team, and 3970 cross-user viewers cannot retrieve the credential. Responses are marked 3971 `Cache-Control: no-store`. 3972 3973 Args: 3974 user: User ID (`usr_...`). The authenticated user, or a user of the app whose secret key is presented. 3975 provider: Integration provider. Only `github` is accepted. 3976 3977 Returns: 3978 Successful response 3979 """ 3980 return self._http.request( 3981 f"/api/v1/users/{user}/integrations/{provider}/access_token", 3982 response_type=IntegrationAccessTokenResponse, 3983 )
IntegrationResource(http: archastro.platform.runtime.http_client.SyncHttpClient)
3962 def access_token(self, user: str, provider: str) -> IntegrationAccessTokenResponse: 3963 """ 3964 Retrieve a GitHub integration access token 3965 Returns a valid GitHub access token for one integration owned by the 3966 authenticated user. Expired tokens are refreshed before the response is 3967 returned. 3968 This endpoint accepts the user's own bearer token, or the app's secret key 3969 acting server-to-server for one of its users. Developer, agent, team, and 3970 cross-user viewers cannot retrieve the credential. Responses are marked 3971 `Cache-Control: no-store`. 3972 3973 Args: 3974 user: User ID (`usr_...`). The authenticated user, or a user of the app whose secret key is presented. 3975 provider: Integration provider. Only `github` is accepted. 3976 3977 Returns: 3978 Successful response 3979 """ 3980 return self._http.request( 3981 f"/api/v1/users/{user}/integrations/{provider}/access_token", 3982 response_type=IntegrationAccessTokenResponse, 3983 )
Retrieve a GitHub integration access token
Returns a valid GitHub access token for one integration owned by the
authenticated user. Expired tokens are refreshed before the response is
returned.
This endpoint accepts the user's own bearer token, or the app's secret key
acting server-to-server for one of its users. Developer, agent, team, and
cross-user viewers cannot retrieve the credential. Responses are marked
Cache-Control: no-store.
Arguments:
- user: User ID (
usr_...). The authenticated user, or a user of the app whose secret key is presented. - provider: Integration provider. Only
githubis accepted.
Returns:
Successful response
class
UserSshKeyResource:
3986class UserSshKeyResource: 3987 def __init__(self, http: SyncHttpClient): 3988 self._http = http 3989 3990 def list( 3991 self, user: str, *, limit: int | None = None, after_cursor: str | None = None 3992 ) -> UserSshKeyListResponse: 3993 """ 3994 List registered SSH keys 3995 Returns a cursor-paginated page of SSH-key metadata for the authenticated user. 3996 3997 Args: 3998 user: User ID (`usr_...`) or `me`. 3999 limit: Maximum keys per page. Defaults to 50; maximum is 100. 4000 after_cursor: Opaque cursor for the next page of older keys. 4001 4002 Returns: 4003 Successful response 4004 """ 4005 query: dict[str, object] = {} 4006 if limit is not None: 4007 query["limit"] = limit 4008 if after_cursor is not None: 4009 query["after_cursor"] = after_cursor 4010 return self._http.request( 4011 f"/api/v1/users/{user}/ssh_keys", 4012 query=query, 4013 response_type=UserSshKeyListResponse, 4014 ) 4015 4016 def create(self, user: str, input: UserSshKeyCreateInput) -> UserSSHKey: 4017 """ 4018 Register an SSH public key 4019 Registers one comment-free Ed25519 public key for Git-over-SSH. The key is 4020 encrypted before storage; responses expose only its label, algorithm and 4021 OpenSSH SHA-256 fingerprint. 4022 The caller must be the user named by `user` and must present a first-party 4023 session or a `full_access` personal access token. 4024 4025 Args: 4026 user: User ID (`usr_...`) or `me`. 4027 input: Request body. 4028 input.label: A label such as `Work laptop`. 4029 input.public_key: One `ssh-ed25519 <base64>` public key without options or a comment. 4030 4031 Returns: 4032 Metadata for the registered key; no key material. 4033 """ 4034 return self._http.request( 4035 f"/api/v1/users/{user}/ssh_keys", 4036 method="POST", 4037 body=input, 4038 response_type=UserSSHKey, 4039 )
UserSshKeyResource(http: archastro.platform.runtime.http_client.SyncHttpClient)
def
list( self, user: str, *, limit: int | None = None, after_cursor: str | None = None) -> UserSshKeyListResponse:
3990 def list( 3991 self, user: str, *, limit: int | None = None, after_cursor: str | None = None 3992 ) -> UserSshKeyListResponse: 3993 """ 3994 List registered SSH keys 3995 Returns a cursor-paginated page of SSH-key metadata for the authenticated user. 3996 3997 Args: 3998 user: User ID (`usr_...`) or `me`. 3999 limit: Maximum keys per page. Defaults to 50; maximum is 100. 4000 after_cursor: Opaque cursor for the next page of older keys. 4001 4002 Returns: 4003 Successful response 4004 """ 4005 query: dict[str, object] = {} 4006 if limit is not None: 4007 query["limit"] = limit 4008 if after_cursor is not None: 4009 query["after_cursor"] = after_cursor 4010 return self._http.request( 4011 f"/api/v1/users/{user}/ssh_keys", 4012 query=query, 4013 response_type=UserSshKeyListResponse, 4014 )
List registered SSH keys Returns a cursor-paginated page of SSH-key metadata for the authenticated user.
Arguments:
- user: User ID (
usr_...) orme. - limit: Maximum keys per page. Defaults to 50; maximum is 100.
- after_cursor: Opaque cursor for the next page of older keys.
Returns:
Successful response
def
create( self, user: str, input: UserSshKeyCreateInput) -> archastro.platform.types.users.UserSSHKey:
4016 def create(self, user: str, input: UserSshKeyCreateInput) -> UserSSHKey: 4017 """ 4018 Register an SSH public key 4019 Registers one comment-free Ed25519 public key for Git-over-SSH. The key is 4020 encrypted before storage; responses expose only its label, algorithm and 4021 OpenSSH SHA-256 fingerprint. 4022 The caller must be the user named by `user` and must present a first-party 4023 session or a `full_access` personal access token. 4024 4025 Args: 4026 user: User ID (`usr_...`) or `me`. 4027 input: Request body. 4028 input.label: A label such as `Work laptop`. 4029 input.public_key: One `ssh-ed25519 <base64>` public key without options or a comment. 4030 4031 Returns: 4032 Metadata for the registered key; no key material. 4033 """ 4034 return self._http.request( 4035 f"/api/v1/users/{user}/ssh_keys", 4036 method="POST", 4037 body=input, 4038 response_type=UserSSHKey, 4039 )
Register an SSH public key
Registers one comment-free Ed25519 public key for Git-over-SSH. The key is
encrypted before storage; responses expose only its label, algorithm and
OpenSSH SHA-256 fingerprint.
The caller must be the user named by user and must present a first-party
session or a full_access personal access token.
Arguments:
- user: User ID (
usr_...) orme. - input: Request body.
- input.label: A label such as
Work laptop. - input.public_key: One
ssh-ed25519 <base64>public key without options or a comment.
Returns:
Metadata for the registered key; no key material.
class
UserTaskResource:
4042class UserTaskResource: 4043 def __init__(self, http: SyncHttpClient): 4044 self._http = http 4045 4046 def list( 4047 self, 4048 user: str, 4049 *, 4050 team: str | None = None, 4051 org: str | None = None, 4052 status: str | None = None, 4053 owner_user: str | None = None, 4054 owner_agent: str | None = None, 4055 priority: int | None = None, 4056 tag: str | None = None, 4057 parent: str | None = None, 4058 source_scope: str | None = None, 4059 source_type: str | None = None, 4060 source_id: str | None = None, 4061 epic: str | None = None, 4062 search: str | None = None, 4063 sort: str | None = None, 4064 order: str | None = None, 4065 due_before: str | None = None, 4066 due_after: str | None = None, 4067 overdue: bool | None = None, 4068 ready: bool | None = None, 4069 attention: bool | None = None, 4070 limit: int | None = None, 4071 after_cursor: str | None = None, 4072 ) -> UserTaskListResponse: 4073 """ 4074 List an owner's tasks 4075 Returns tasks owned by the specified user or team. You can narrow results using the 4076 optional filters below. By default results are returned in reverse chronological 4077 order (most recently created first); use `sort` and `order` to sort by due date or 4078 priority instead. 4079 User-authenticated callers may list their personal tasks or tasks for teams they 4080 have joined. Privileged callers provide the owner in the route; the owner's 4081 organization is implied by that principal. An explicit `org` is optional and, 4082 when set, must match the owner's organization. 4083 4084 Args: 4085 user: User ID (`usr_...`) for user-scoped tasks. 4086 team: Team ID (`tem_...`). Only tasks belonging to this team are returned. 4087 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. 4088 status: Filter tasks by status. One of `"open"`, `"in_progress"`, `"in_review"`, or `"done"`. Omit to return tasks in all statuses. 4089 owner_user: Filter tasks assigned to a specific user. Provide the user's public ID (`usr_...`). 4090 owner_agent: Filter tasks assigned to a specific agent. Provide the agent's public ID (`agi_...`). 4091 priority: Filter tasks by priority, from 0 (highest) to 4 (lowest). 4092 tag: Return only tasks carrying this tag (matched against the canonical lowercase form). 4093 parent: Return only subtasks of the given task (`tsk_...`), or pass `none` to return only top-level tasks. 4094 source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 4095 source_type: Return only tasks whose source matches this object kind. Must be supplied with the other source filters. 4096 source_id: Return only tasks whose source matches this object identity. Must be supplied with the other source filters. 4097 epic: Return only tasks with this exact epic label. 4098 search: Restrict results to tasks whose name or description contains this string. 4099 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. 4100 order: Sort direction, `"asc"` or `"desc"`. Defaults to `"desc"` for `created` and `"asc"` for `due_date` and `priority`. 4101 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. 4102 due_after: Return only tasks with a due date strictly after this ISO 8601 datetime or date. Tasks without a due date are excluded. 4103 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. 4104 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. 4105 attention: When true, return paused, failed, or in-progress tasks with no lease or a past lease expiry. 4106 limit: Maximum number of tasks to return. Capped at 100. 4107 after_cursor: Opaque cursor returned by the previous page. 4108 4109 Returns: 4110 Successful response 4111 """ 4112 query: dict[str, object] = {} 4113 if team is not None: 4114 query["team"] = team 4115 if org is not None: 4116 query["org"] = org 4117 if status is not None: 4118 query["status"] = status 4119 if owner_user is not None: 4120 query["owner_user"] = owner_user 4121 if owner_agent is not None: 4122 query["owner_agent"] = owner_agent 4123 if priority is not None: 4124 query["priority"] = priority 4125 if tag is not None: 4126 query["tag"] = tag 4127 if parent is not None: 4128 query["parent"] = parent 4129 if source_scope is not None: 4130 query["source_scope"] = source_scope 4131 if source_type is not None: 4132 query["source_type"] = source_type 4133 if source_id is not None: 4134 query["source_id"] = source_id 4135 if epic is not None: 4136 query["epic"] = epic 4137 if search is not None: 4138 query["search"] = search 4139 if sort is not None: 4140 query["sort"] = sort 4141 if order is not None: 4142 query["order"] = order 4143 if due_before is not None: 4144 query["due_before"] = due_before 4145 if due_after is not None: 4146 query["due_after"] = due_after 4147 if overdue is not None: 4148 query["overdue"] = overdue 4149 if ready is not None: 4150 query["ready"] = ready 4151 if attention is not None: 4152 query["attention"] = attention 4153 if limit is not None: 4154 query["limit"] = limit 4155 if after_cursor is not None: 4156 query["after_cursor"] = after_cursor 4157 return self._http.request( 4158 f"/api/v1/users/{user}/tasks", 4159 query=query, 4160 response_type=UserTaskListResponse, 4161 ) 4162 4163 def create(self, user: str, input: UserTaskCreateInput) -> Task: 4164 """ 4165 Create a task for an owner 4166 Creates a new task owned by the specified user or team and returns the full 4167 task object. User-authenticated calls are attributed to the authenticated 4168 user or agent. App-scoped developer and server-to-server callers must provide 4169 the task's explicit `org` scope and an explicit `user` or `agent` actor for 4170 team tasks; a user-owned task reuses the user in the route unless an explicit 4171 agent is supplied. Every referenced principal is validated against the app, 4172 owner, and team membership before creation. 4173 4174 Args: 4175 user: User ID (`usr_...`) for user-scoped tasks. 4176 input: Request body. 4177 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. 4178 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. 4179 input.task: Attributes for the task to create. `name` is required; all other fields are optional. 4180 input.team: Team ID (`tem_...`). The task will be owned by this team. 4181 4182 Returns: 4183 The newly created task. 4184 """ 4185 return self._http.request( 4186 f"/api/v1/users/{user}/tasks", 4187 method="POST", 4188 body=input, 4189 response_type=Task, 4190 ) 4191 4192 def blocker_cycles( 4193 self, 4194 user: str, 4195 *, 4196 team: str | None = None, 4197 org: str | None = None, 4198 limit: int | None = None, 4199 after_cursor: str | None = None, 4200 ) -> UserTaskBlockerCyclesResponse: 4201 """ 4202 List task blocker cycles 4203 Runs an on-demand diagnostic over unfinished tasks owned by the specified 4204 team or user and returns a forward cursor-paginated page of complete cyclic 4205 blocker components. Detection is bounded to owners with at most 100 4206 unfinished tasks. This endpoint is read-only: cycles do not prevent task 4207 updates, lease acquisition, or completion. 4208 4209 Args: 4210 user: User ID (`usr_...`) for user-scoped tasks. 4211 team: Team ID (`tem_...`) owning the tasks. 4212 org: Optional organization context for privileged callers. 4213 limit: Maximum cycle components to return. Defaults to 50; maximum is 100. 4214 after_cursor: Opaque cursor returned by the preceding page. 4215 4216 Returns: 4217 Successful response 4218 """ 4219 query: dict[str, object] = {} 4220 if team is not None: 4221 query["team"] = team 4222 if org is not None: 4223 query["org"] = org 4224 if limit is not None: 4225 query["limit"] = limit 4226 if after_cursor is not None: 4227 query["after_cursor"] = after_cursor 4228 return self._http.request( 4229 f"/api/v1/users/{user}/tasks/blocker_cycles", 4230 query=query, 4231 response_type=UserTaskBlockerCyclesResponse, 4232 ) 4233 4234 def by_source(self, user: str, input: UserTaskBySourceInput) -> TaskEnsureResult: 4235 """ 4236 Find or create a task by source 4237 Atomically creates one task per owner, tenant and source. Retries return the current task without updating it. Historical tasks created through ordinary create are not adopted. 4238 4239 Args: 4240 user: User ID (`usr_...`) for user-scoped tasks. 4241 input: Request body. 4242 input.agent: Explicit acting agent for privileged callers. 4243 input.description: Initial task description. 4244 input.epic: Initial epic grouping. 4245 input.name: Initial task name. 4246 input.org: Explicit organization for privileged callers. 4247 input.source_id: Source identity, for example owner/repo#123. 4248 input.source_scope: Source scope, for example github. 4249 input.source_type: Source type, for example pull_request. 4250 input.status: Initial task status. 4251 input.team: Team owner. 4252 4253 Returns: 4254 The task and whether this request created it. 4255 """ 4256 return self._http.request( 4257 f"/api/v1/users/{user}/tasks/by-source", 4258 method="PUT", 4259 body=input, 4260 response_type=TaskEnsureResult, 4261 ) 4262 4263 def ready( 4264 self, 4265 user: str, 4266 *, 4267 team: str | None = None, 4268 org: str | None = None, 4269 explain: bool | None = None, 4270 assigned_to_me: bool | None = None, 4271 source_scope: str | None = None, 4272 source_type: str | None = None, 4273 source_id: str | None = None, 4274 epic: str | None = None, 4275 limit: int | None = None, 4276 after_cursor: str | None = None, 4277 ) -> UserTaskReadyResponse: 4278 """ 4279 List an owner's ready tasks 4280 Returns open tasks with no unfinished blockers and no active session lease. 4281 Readiness is calculated by the server from the current task projection. It is 4282 a snapshot, not a reservation; claim a task lease before starting work. 4283 Results are ordered by priority (0, the most urgent, first), then oldest 4284 first, so the first page is always the most urgent ready work. 4285 Pass `explain=true` to include every open task with a stable readiness reason. 4286 4287 Args: 4288 user: User ID (`usr_...`) for user-scoped tasks. 4289 team: Team ID (`tem_...`) owning the tasks. 4290 org: Optional organization context for privileged callers. 4291 explain: Include blocked and actively leased open tasks with exclusion reasons. 4292 assigned_to_me: Only include tasks assigned to the authenticated user. 4293 source_scope: Only include tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 4294 source_type: Only include tasks whose source matches this object kind. 4295 source_id: Only include tasks whose source matches this object identity. 4296 epic: Only include tasks with this exact epic label. 4297 limit: Maximum number of readiness entries to return. Capped at 100. 4298 after_cursor: Opaque cursor returned by the previous page. 4299 4300 Returns: 4301 Successful response 4302 """ 4303 query: dict[str, object] = {} 4304 if team is not None: 4305 query["team"] = team 4306 if org is not None: 4307 query["org"] = org 4308 if explain is not None: 4309 query["explain"] = explain 4310 if assigned_to_me is not None: 4311 query["assigned_to_me"] = assigned_to_me 4312 if source_scope is not None: 4313 query["source_scope"] = source_scope 4314 if source_type is not None: 4315 query["source_type"] = source_type 4316 if source_id is not None: 4317 query["source_id"] = source_id 4318 if epic is not None: 4319 query["epic"] = epic 4320 if limit is not None: 4321 query["limit"] = limit 4322 if after_cursor is not None: 4323 query["after_cursor"] = after_cursor 4324 return self._http.request( 4325 f"/api/v1/users/{user}/tasks/ready", 4326 query=query, 4327 response_type=UserTaskReadyResponse, 4328 ) 4329 4330 def search( 4331 self, 4332 user: str, 4333 *, 4334 team: str | None = None, 4335 org: str | None = None, 4336 q: str | None = None, 4337 query: str | None = None, 4338 status: str | None = None, 4339 owner_user: str | None = None, 4340 owner_agent: str | None = None, 4341 priority: int | None = None, 4342 tag: str | None = None, 4343 parent: str | None = None, 4344 source_scope: str | None = None, 4345 source_type: str | None = None, 4346 source_id: str | None = None, 4347 epic: str | None = None, 4348 limit: int | None = None, 4349 after_cursor: str | None = None, 4350 ) -> UserTaskSearchResponse: 4351 """ 4352 Search an owner's tasks 4353 Performs a full-text search over tasks owned by the specified user or team and returns 4354 matching results. Combine `q` with the optional filters to narrow the result set 4355 further. When no query is provided, the endpoint behaves like a filtered list. 4356 The `query` field in the response echoes the effective search query. 4357 User-authenticated callers may search their personal tasks or tasks for teams 4358 they have joined. Privileged callers provide the owner in the route; the owner's 4359 organization is implied by that principal. An explicit `org` is optional and, 4360 when set, must match the owner's organization. 4361 4362 Args: 4363 user: User ID (`usr_...`) for user-scoped tasks. 4364 team: Team ID (`tem_...`). Only tasks belonging to this team are searched. 4365 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. 4366 q: Full-text search query matched against task names and descriptions. Takes precedence over `query` when both are provided. 4367 query: Alias for `q`. Use `q` when possible; this parameter exists for compatibility. 4368 status: Filter results by status. One of `"open"`, `"in_progress"`, `"in_review"`, or `"done"`. Omit to include all statuses. 4369 owner_user: Restrict results to tasks assigned to the user with this public ID (`usr_...`). 4370 owner_agent: Restrict results to tasks assigned to the agent with this public ID (`agi_...`). 4371 priority: Filter results by priority, from 0 (highest) to 4 (lowest). 4372 tag: Return only tasks carrying this tag (matched against the canonical lowercase form). 4373 parent: Return only subtasks of the given task (`tsk_...`), or pass `none` to return only top-level tasks. 4374 source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 4375 source_type: Return only tasks whose source matches this object kind. 4376 source_id: Return only tasks whose source matches this object identity. 4377 epic: Return only tasks with this exact epic label. 4378 limit: Maximum number of tasks to return. Capped at 100. 4379 after_cursor: Opaque cursor returned by the previous page. 4380 4381 Returns: 4382 Successful response 4383 """ 4384 query: dict[str, object] = {} 4385 if team is not None: 4386 query["team"] = team 4387 if org is not None: 4388 query["org"] = org 4389 if q is not None: 4390 query["q"] = q 4391 if query is not None: 4392 query["query"] = query 4393 if status is not None: 4394 query["status"] = status 4395 if owner_user is not None: 4396 query["owner_user"] = owner_user 4397 if owner_agent is not None: 4398 query["owner_agent"] = owner_agent 4399 if priority is not None: 4400 query["priority"] = priority 4401 if tag is not None: 4402 query["tag"] = tag 4403 if parent is not None: 4404 query["parent"] = parent 4405 if source_scope is not None: 4406 query["source_scope"] = source_scope 4407 if source_type is not None: 4408 query["source_type"] = source_type 4409 if source_id is not None: 4410 query["source_id"] = source_id 4411 if epic is not None: 4412 query["epic"] = epic 4413 if limit is not None: 4414 query["limit"] = limit 4415 if after_cursor is not None: 4416 query["after_cursor"] = after_cursor 4417 return self._http.request( 4418 f"/api/v1/users/{user}/tasks/search", 4419 query=query, 4420 response_type=UserTaskSearchResponse, 4421 )
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, attention: bool | None = None, limit: int | None = None, after_cursor: str | None = None) -> UserTaskListResponse:
4046 def list( 4047 self, 4048 user: str, 4049 *, 4050 team: str | None = None, 4051 org: str | None = None, 4052 status: str | None = None, 4053 owner_user: str | None = None, 4054 owner_agent: str | None = None, 4055 priority: int | None = None, 4056 tag: str | None = None, 4057 parent: str | None = None, 4058 source_scope: str | None = None, 4059 source_type: str | None = None, 4060 source_id: str | None = None, 4061 epic: str | None = None, 4062 search: str | None = None, 4063 sort: str | None = None, 4064 order: str | None = None, 4065 due_before: str | None = None, 4066 due_after: str | None = None, 4067 overdue: bool | None = None, 4068 ready: bool | None = None, 4069 attention: bool | None = None, 4070 limit: int | None = None, 4071 after_cursor: str | None = None, 4072 ) -> UserTaskListResponse: 4073 """ 4074 List an owner's tasks 4075 Returns tasks owned by the specified user or team. You can narrow results using the 4076 optional filters below. By default results are returned in reverse chronological 4077 order (most recently created first); use `sort` and `order` to sort by due date or 4078 priority instead. 4079 User-authenticated callers may list their personal tasks or tasks for teams they 4080 have joined. Privileged callers provide the owner in the route; the owner's 4081 organization is implied by that principal. An explicit `org` is optional and, 4082 when set, must match the owner's organization. 4083 4084 Args: 4085 user: User ID (`usr_...`) for user-scoped tasks. 4086 team: Team ID (`tem_...`). Only tasks belonging to this team are returned. 4087 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. 4088 status: Filter tasks by status. One of `"open"`, `"in_progress"`, `"in_review"`, or `"done"`. Omit to return tasks in all statuses. 4089 owner_user: Filter tasks assigned to a specific user. Provide the user's public ID (`usr_...`). 4090 owner_agent: Filter tasks assigned to a specific agent. Provide the agent's public ID (`agi_...`). 4091 priority: Filter tasks by priority, from 0 (highest) to 4 (lowest). 4092 tag: Return only tasks carrying this tag (matched against the canonical lowercase form). 4093 parent: Return only subtasks of the given task (`tsk_...`), or pass `none` to return only top-level tasks. 4094 source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 4095 source_type: Return only tasks whose source matches this object kind. Must be supplied with the other source filters. 4096 source_id: Return only tasks whose source matches this object identity. Must be supplied with the other source filters. 4097 epic: Return only tasks with this exact epic label. 4098 search: Restrict results to tasks whose name or description contains this string. 4099 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. 4100 order: Sort direction, `"asc"` or `"desc"`. Defaults to `"desc"` for `created` and `"asc"` for `due_date` and `priority`. 4101 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. 4102 due_after: Return only tasks with a due date strictly after this ISO 8601 datetime or date. Tasks without a due date are excluded. 4103 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. 4104 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. 4105 attention: When true, return paused, failed, or in-progress tasks with no lease or a past lease expiry. 4106 limit: Maximum number of tasks to return. Capped at 100. 4107 after_cursor: Opaque cursor returned by the previous page. 4108 4109 Returns: 4110 Successful response 4111 """ 4112 query: dict[str, object] = {} 4113 if team is not None: 4114 query["team"] = team 4115 if org is not None: 4116 query["org"] = org 4117 if status is not None: 4118 query["status"] = status 4119 if owner_user is not None: 4120 query["owner_user"] = owner_user 4121 if owner_agent is not None: 4122 query["owner_agent"] = owner_agent 4123 if priority is not None: 4124 query["priority"] = priority 4125 if tag is not None: 4126 query["tag"] = tag 4127 if parent is not None: 4128 query["parent"] = parent 4129 if source_scope is not None: 4130 query["source_scope"] = source_scope 4131 if source_type is not None: 4132 query["source_type"] = source_type 4133 if source_id is not None: 4134 query["source_id"] = source_id 4135 if epic is not None: 4136 query["epic"] = epic 4137 if search is not None: 4138 query["search"] = search 4139 if sort is not None: 4140 query["sort"] = sort 4141 if order is not None: 4142 query["order"] = order 4143 if due_before is not None: 4144 query["due_before"] = due_before 4145 if due_after is not None: 4146 query["due_after"] = due_after 4147 if overdue is not None: 4148 query["overdue"] = overdue 4149 if ready is not None: 4150 query["ready"] = ready 4151 if attention is not None: 4152 query["attention"] = attention 4153 if limit is not None: 4154 query["limit"] = limit 4155 if after_cursor is not None: 4156 query["after_cursor"] = after_cursor 4157 return self._http.request( 4158 f"/api/v1/users/{user}/tasks", 4159 query=query, 4160 response_type=UserTaskListResponse, 4161 )
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","in_review", or"done". Omit to return tasks in all statuses. - owner_user: Filter tasks assigned to a specific user. Provide the user's public ID (
usr_...). - owner_agent: Filter tasks assigned to a specific agent. Provide the agent's public ID (
agi_...). - priority: Filter tasks by priority, from 0 (highest) to 4 (lowest).
- tag: Return only tasks carrying this tag (matched against the canonical lowercase form).
- parent: Return only subtasks of the given task (
tsk_...), or passnoneto return only top-level tasks. - source_scope: Return only tasks whose source matches this container. Must be supplied with
source_typeandsource_id. - source_type: Return only tasks whose source matches this object kind. Must be supplied with the other source filters.
- source_id: Return only tasks whose source matches this object identity. Must be supplied with the other source filters.
- epic: Return only tasks with this exact epic label.
- search: Restrict results to tasks whose name or description contains this string.
- sort: Sort key. One of
"created"(default most recently created first),"due_date"(soonest due first; tasks without a due date always sort last), or"priority"(most urgent first). Ties break by most recently created. - order: Sort direction,
"asc"or"desc". Defaults to"desc"forcreatedand"asc"fordue_dateandpriority. - due_before: Return only tasks with a due date strictly before this ISO 8601 datetime (
2026-08-01T00:00:00Z) or date (2026-08-01, meaning midnight UTC). Tasks without a due date are excluded. - due_after: Return only tasks with a due date strictly after this ISO 8601 datetime or date. Tasks without a due date are excluded.
- overdue: When
true, return only overdue tasks: a due date before the current UTC day and a status other than"done". A task due today is not overdue. - ready: When true, return only open tasks with no unfinished blockers and no active session lease. This is a projection snapshot; claim a lease before starting work.
- attention: When true, return paused, failed, or in-progress tasks with no lease or a past lease expiry.
- limit: Maximum number of tasks to return. Capped at 100.
- after_cursor: Opaque cursor returned by the previous page.
Returns:
Successful response
4163 def create(self, user: str, input: UserTaskCreateInput) -> Task: 4164 """ 4165 Create a task for an owner 4166 Creates a new task owned by the specified user or team and returns the full 4167 task object. User-authenticated calls are attributed to the authenticated 4168 user or agent. App-scoped developer and server-to-server callers must provide 4169 the task's explicit `org` scope and an explicit `user` or `agent` actor for 4170 team tasks; a user-owned task reuses the user in the route unless an explicit 4171 agent is supplied. Every referenced principal is validated against the app, 4172 owner, and team membership before creation. 4173 4174 Args: 4175 user: User ID (`usr_...`) for user-scoped tasks. 4176 input: Request body. 4177 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. 4178 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. 4179 input.task: Attributes for the task to create. `name` is required; all other fields are optional. 4180 input.team: Team ID (`tem_...`). The task will be owned by this team. 4181 4182 Returns: 4183 The newly created task. 4184 """ 4185 return self._http.request( 4186 f"/api/v1/users/{user}/tasks", 4187 method="POST", 4188 body=input, 4189 response_type=Task, 4190 )
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:
4192 def blocker_cycles( 4193 self, 4194 user: str, 4195 *, 4196 team: str | None = None, 4197 org: str | None = None, 4198 limit: int | None = None, 4199 after_cursor: str | None = None, 4200 ) -> UserTaskBlockerCyclesResponse: 4201 """ 4202 List task blocker cycles 4203 Runs an on-demand diagnostic over unfinished tasks owned by the specified 4204 team or user and returns a forward cursor-paginated page of complete cyclic 4205 blocker components. Detection is bounded to owners with at most 100 4206 unfinished tasks. This endpoint is read-only: cycles do not prevent task 4207 updates, lease acquisition, or completion. 4208 4209 Args: 4210 user: User ID (`usr_...`) for user-scoped tasks. 4211 team: Team ID (`tem_...`) owning the tasks. 4212 org: Optional organization context for privileged callers. 4213 limit: Maximum cycle components to return. Defaults to 50; maximum is 100. 4214 after_cursor: Opaque cursor returned by the preceding page. 4215 4216 Returns: 4217 Successful response 4218 """ 4219 query: dict[str, object] = {} 4220 if team is not None: 4221 query["team"] = team 4222 if org is not None: 4223 query["org"] = org 4224 if limit is not None: 4225 query["limit"] = limit 4226 if after_cursor is not None: 4227 query["after_cursor"] = after_cursor 4228 return self._http.request( 4229 f"/api/v1/users/{user}/tasks/blocker_cycles", 4230 query=query, 4231 response_type=UserTaskBlockerCyclesResponse, 4232 )
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
by_source( self, user: str, input: UserTaskBySourceInput) -> archastro.platform.types.tasks.TaskEnsureResult:
4234 def by_source(self, user: str, input: UserTaskBySourceInput) -> TaskEnsureResult: 4235 """ 4236 Find or create a task by source 4237 Atomically creates one task per owner, tenant and source. Retries return the current task without updating it. Historical tasks created through ordinary create are not adopted. 4238 4239 Args: 4240 user: User ID (`usr_...`) for user-scoped tasks. 4241 input: Request body. 4242 input.agent: Explicit acting agent for privileged callers. 4243 input.description: Initial task description. 4244 input.epic: Initial epic grouping. 4245 input.name: Initial task name. 4246 input.org: Explicit organization for privileged callers. 4247 input.source_id: Source identity, for example owner/repo#123. 4248 input.source_scope: Source scope, for example github. 4249 input.source_type: Source type, for example pull_request. 4250 input.status: Initial task status. 4251 input.team: Team owner. 4252 4253 Returns: 4254 The task and whether this request created it. 4255 """ 4256 return self._http.request( 4257 f"/api/v1/users/{user}/tasks/by-source", 4258 method="PUT", 4259 body=input, 4260 response_type=TaskEnsureResult, 4261 )
Find or create a task by source Atomically creates one task per owner, tenant and source. Retries return the current task without updating it. Historical tasks created through ordinary create are not adopted.
Arguments:
- user: User ID (
usr_...) for user-scoped tasks. - input: Request body.
- input.agent: Explicit acting agent for privileged callers.
- input.description: Initial task description.
- input.epic: Initial epic grouping.
- input.name: Initial task name.
- input.org: Explicit organization for privileged callers.
- input.source_id: Source identity, for example owner/repo#123.
- input.source_scope: Source scope, for example github.
- input.source_type: Source type, for example pull_request.
- input.status: Initial task status.
- input.team: Team owner.
Returns:
The task and whether this request created it.
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:
4263 def ready( 4264 self, 4265 user: str, 4266 *, 4267 team: str | None = None, 4268 org: str | None = None, 4269 explain: bool | None = None, 4270 assigned_to_me: bool | None = None, 4271 source_scope: str | None = None, 4272 source_type: str | None = None, 4273 source_id: str | None = None, 4274 epic: str | None = None, 4275 limit: int | None = None, 4276 after_cursor: str | None = None, 4277 ) -> UserTaskReadyResponse: 4278 """ 4279 List an owner's ready tasks 4280 Returns open tasks with no unfinished blockers and no active session lease. 4281 Readiness is calculated by the server from the current task projection. It is 4282 a snapshot, not a reservation; claim a task lease before starting work. 4283 Results are ordered by priority (0, the most urgent, first), then oldest 4284 first, so the first page is always the most urgent ready work. 4285 Pass `explain=true` to include every open task with a stable readiness reason. 4286 4287 Args: 4288 user: User ID (`usr_...`) for user-scoped tasks. 4289 team: Team ID (`tem_...`) owning the tasks. 4290 org: Optional organization context for privileged callers. 4291 explain: Include blocked and actively leased open tasks with exclusion reasons. 4292 assigned_to_me: Only include tasks assigned to the authenticated user. 4293 source_scope: Only include tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 4294 source_type: Only include tasks whose source matches this object kind. 4295 source_id: Only include tasks whose source matches this object identity. 4296 epic: Only include tasks with this exact epic label. 4297 limit: Maximum number of readiness entries to return. Capped at 100. 4298 after_cursor: Opaque cursor returned by the previous page. 4299 4300 Returns: 4301 Successful response 4302 """ 4303 query: dict[str, object] = {} 4304 if team is not None: 4305 query["team"] = team 4306 if org is not None: 4307 query["org"] = org 4308 if explain is not None: 4309 query["explain"] = explain 4310 if assigned_to_me is not None: 4311 query["assigned_to_me"] = assigned_to_me 4312 if source_scope is not None: 4313 query["source_scope"] = source_scope 4314 if source_type is not None: 4315 query["source_type"] = source_type 4316 if source_id is not None: 4317 query["source_id"] = source_id 4318 if epic is not None: 4319 query["epic"] = epic 4320 if limit is not None: 4321 query["limit"] = limit 4322 if after_cursor is not None: 4323 query["after_cursor"] = after_cursor 4324 return self._http.request( 4325 f"/api/v1/users/{user}/tasks/ready", 4326 query=query, 4327 response_type=UserTaskReadyResponse, 4328 )
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.
Results are ordered by priority (0, the most urgent, first), then oldest
first, so the first page is always the most urgent ready work.
Pass explain=true to include every open task with a stable readiness reason.
Arguments:
- 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:
4330 def search( 4331 self, 4332 user: str, 4333 *, 4334 team: str | None = None, 4335 org: str | None = None, 4336 q: str | None = None, 4337 query: str | None = None, 4338 status: str | None = None, 4339 owner_user: str | None = None, 4340 owner_agent: str | None = None, 4341 priority: int | None = None, 4342 tag: str | None = None, 4343 parent: str | None = None, 4344 source_scope: str | None = None, 4345 source_type: str | None = None, 4346 source_id: str | None = None, 4347 epic: str | None = None, 4348 limit: int | None = None, 4349 after_cursor: str | None = None, 4350 ) -> UserTaskSearchResponse: 4351 """ 4352 Search an owner's tasks 4353 Performs a full-text search over tasks owned by the specified user or team and returns 4354 matching results. Combine `q` with the optional filters to narrow the result set 4355 further. When no query is provided, the endpoint behaves like a filtered list. 4356 The `query` field in the response echoes the effective search query. 4357 User-authenticated callers may search their personal tasks or tasks for teams 4358 they have joined. Privileged callers provide the owner in the route; the owner's 4359 organization is implied by that principal. An explicit `org` is optional and, 4360 when set, must match the owner's organization. 4361 4362 Args: 4363 user: User ID (`usr_...`) for user-scoped tasks. 4364 team: Team ID (`tem_...`). Only tasks belonging to this team are searched. 4365 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. 4366 q: Full-text search query matched against task names and descriptions. Takes precedence over `query` when both are provided. 4367 query: Alias for `q`. Use `q` when possible; this parameter exists for compatibility. 4368 status: Filter results by status. One of `"open"`, `"in_progress"`, `"in_review"`, or `"done"`. Omit to include all statuses. 4369 owner_user: Restrict results to tasks assigned to the user with this public ID (`usr_...`). 4370 owner_agent: Restrict results to tasks assigned to the agent with this public ID (`agi_...`). 4371 priority: Filter results by priority, from 0 (highest) to 4 (lowest). 4372 tag: Return only tasks carrying this tag (matched against the canonical lowercase form). 4373 parent: Return only subtasks of the given task (`tsk_...`), or pass `none` to return only top-level tasks. 4374 source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 4375 source_type: Return only tasks whose source matches this object kind. 4376 source_id: Return only tasks whose source matches this object identity. 4377 epic: Return only tasks with this exact epic label. 4378 limit: Maximum number of tasks to return. Capped at 100. 4379 after_cursor: Opaque cursor returned by the previous page. 4380 4381 Returns: 4382 Successful response 4383 """ 4384 query: dict[str, object] = {} 4385 if team is not None: 4386 query["team"] = team 4387 if org is not None: 4388 query["org"] = org 4389 if q is not None: 4390 query["q"] = q 4391 if query is not None: 4392 query["query"] = query 4393 if status is not None: 4394 query["status"] = status 4395 if owner_user is not None: 4396 query["owner_user"] = owner_user 4397 if owner_agent is not None: 4398 query["owner_agent"] = owner_agent 4399 if priority is not None: 4400 query["priority"] = priority 4401 if tag is not None: 4402 query["tag"] = tag 4403 if parent is not None: 4404 query["parent"] = parent 4405 if source_scope is not None: 4406 query["source_scope"] = source_scope 4407 if source_type is not None: 4408 query["source_type"] = source_type 4409 if source_id is not None: 4410 query["source_id"] = source_id 4411 if epic is not None: 4412 query["epic"] = epic 4413 if limit is not None: 4414 query["limit"] = limit 4415 if after_cursor is not None: 4416 query["after_cursor"] = after_cursor 4417 return self._http.request( 4418 f"/api/v1/users/{user}/tasks/search", 4419 query=query, 4420 response_type=UserTaskSearchResponse, 4421 )
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","in_review", 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:
4424class UserThreadResource: 4425 def __init__(self, http: SyncHttpClient): 4426 self._http = http 4427 4428 def list( 4429 self, 4430 user: str, 4431 *, 4432 agent: builtins.list[str] | None = None, 4433 filter: builtins.list[dict[str, Any]] | None = None, 4434 ) -> UserThreadListResponse: 4435 """ 4436 List threads for a user 4437 Returns all threads visible to the specified user. The authenticated caller must 4438 have access to the target user's account; a 403 is returned otherwise. 4439 Pass one or more `agent` IDs to narrow results to threads where at least one of 4440 the listed agents is also a member useful for displaying every thread a user 4441 shares with a particular agent. Pass one or more `filter` objects to narrow 4442 results by thread metadata key/value pairs. Both narrowings may be combined in 4443 a single request. 4444 Results are returned as a flat array; no cursor-based pagination is applied. 4445 Threads are ordered with default threads first, then by most recent activity 4446 (newest first), each carrying a `last_activity` timestamp. 4447 4448 Args: 4449 user: User ID (`usr_...`) whose threads should be listed. 4450 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. 4451 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. 4452 4453 Returns: 4454 Successful response 4455 """ 4456 query: dict[str, object] = {} 4457 if agent is not None: 4458 query["agent"] = agent 4459 if filter is not None: 4460 query["filter"] = filter 4461 return self._http.request( 4462 f"/api/v1/users/{user}/threads", 4463 query=query, 4464 response_type=UserThreadListResponse, 4465 ) 4466 4467 def create(self, user: str, input: UserThreadCreateInput) -> Thread: 4468 """ 4469 Create a thread for a user 4470 Creates a new thread owned by the specified user. The authenticated caller must 4471 have access to the target user's account; a 403 is returned otherwise. 4472 An automatic welcome message is sent into the thread upon creation unless 4473 `skip_welcome_message` is set to `true`. The thread is immediately visible to 4474 the owning user and any members added at creation time. 4475 4476 Args: 4477 user: User ID (`usr_...`) whose threads should be listed. 4478 input: Request body. 4479 input.skip_welcome_message: When `true`, suppresses the automatic welcome message that is otherwise sent into the thread on creation. Defaults to `false`. 4480 input.thread: Attributes for the new thread. See ThreadCreateParams for the full set of accepted fields. 4481 4482 Returns: 4483 The newly created thread object. 4484 """ 4485 return self._http.request( 4486 f"/api/v1/users/{user}/threads", 4487 method="POST", 4488 body=input, 4489 response_type=Thread, 4490 )
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:
4428 def list( 4429 self, 4430 user: str, 4431 *, 4432 agent: builtins.list[str] | None = None, 4433 filter: builtins.list[dict[str, Any]] | None = None, 4434 ) -> UserThreadListResponse: 4435 """ 4436 List threads for a user 4437 Returns all threads visible to the specified user. The authenticated caller must 4438 have access to the target user's account; a 403 is returned otherwise. 4439 Pass one or more `agent` IDs to narrow results to threads where at least one of 4440 the listed agents is also a member useful for displaying every thread a user 4441 shares with a particular agent. Pass one or more `filter` objects to narrow 4442 results by thread metadata key/value pairs. Both narrowings may be combined in 4443 a single request. 4444 Results are returned as a flat array; no cursor-based pagination is applied. 4445 Threads are ordered with default threads first, then by most recent activity 4446 (newest first), each carrying a `last_activity` timestamp. 4447 4448 Args: 4449 user: User ID (`usr_...`) whose threads should be listed. 4450 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. 4451 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. 4452 4453 Returns: 4454 Successful response 4455 """ 4456 query: dict[str, object] = {} 4457 if agent is not None: 4458 query["agent"] = agent 4459 if filter is not None: 4460 query["filter"] = filter 4461 return self._http.request( 4462 f"/api/v1/users/{user}/threads", 4463 query=query, 4464 response_type=UserThreadListResponse, 4465 )
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:
4467 def create(self, user: str, input: UserThreadCreateInput) -> Thread: 4468 """ 4469 Create a thread for a user 4470 Creates a new thread owned by the specified user. The authenticated caller must 4471 have access to the target user's account; a 403 is returned otherwise. 4472 An automatic welcome message is sent into the thread upon creation unless 4473 `skip_welcome_message` is set to `true`. The thread is immediately visible to 4474 the owning user and any members added at creation time. 4475 4476 Args: 4477 user: User ID (`usr_...`) whose threads should be listed. 4478 input: Request body. 4479 input.skip_welcome_message: When `true`, suppresses the automatic welcome message that is otherwise sent into the thread on creation. Defaults to `false`. 4480 input.thread: Attributes for the new thread. See ThreadCreateParams for the full set of accepted fields. 4481 4482 Returns: 4483 The newly created thread object. 4484 """ 4485 return self._http.request( 4486 f"/api/v1/users/{user}/threads", 4487 method="POST", 4488 body=input, 4489 response_type=Thread, 4490 )
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:
4493class TokenResource: 4494 def __init__(self, http: SyncHttpClient): 4495 self._http = http 4496 4497 def list(self, user: str) -> TokenListResponse: 4498 """ 4499 List personal access tokens 4500 Returns all access tokens associated with the authenticated user, including 4501 active and revoked tokens. Tokens are returned without their raw JWT values 4502 the plaintext JWT is only available at creation time. 4503 The caller must be the user identified by `user` and must present a 4504 first-party session (or a `full_access` access token). 4505 4506 Args: 4507 user: User ID (`usr_...`) or `me` for the authenticated user. 4508 4509 Returns: 4510 Successful response 4511 """ 4512 return self._http.request(f"/api/v1/users/{user}/tokens", response_type=TokenListResponse) 4513 4514 def create(self, user: str, input: TokenCreateInput) -> SystemAccessToken: 4515 """ 4516 Create a personal access token 4517 Issues a new long-lived access token for the authenticated user. The raw 4518 JWT is returned in the `token` field of the response exactly once and 4519 cannot be retrieved again store it securely immediately after creation. 4520 `scopes` is optional. When omitted the token receives `full_access`. 4521 Known catalog scopes (for example `profile`) restrict the token through 4522 the same `ScopeGuard` used by OAuth. 4523 `expires_in_days` is optional and must be one of `7`, `30`, `60`, `90`, 4524 or `365`. When omitted the token lasts 30 days. Each user may hold at 4525 most 50 active tokens; exceeding that limit returns 429. 4526 The caller must be the user identified by `user` and must present a 4527 first-party session (or a `full_access` access token). A restricted 4528 access token cannot mint another token. 4529 4530 Args: 4531 user: User ID (`usr_...`) or `me` for the authenticated user. 4532 input: Request body. 4533 input.expires_in_days: Lifetime in days. One of `7`, `30`, `60`, `90`, or `365`. Defaults to `30`. 4534 input.name: Human-readable label for the token (e.g. `"Codex MCP"`). Stored as metadata only. 4535 input.scopes: Optional OAuth scopes to stamp on the token. Omit for `full_access`. 4536 4537 Returns: 4538 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. 4539 """ 4540 return self._http.request( 4541 f"/api/v1/users/{user}/tokens", 4542 method="POST", 4543 body=input, 4544 response_type=SystemAccessToken, 4545 ) 4546 4547 def delete(self, user: str, token: str) -> SystemAccessToken: 4548 """ 4549 Revoke a personal access token 4550 Permanently revokes the specified access token belonging to the 4551 authenticated user. Once revoked, the token is immediately rejected by 4552 all API endpoints and cannot be reinstated. The token record is retained 4553 and returned in the response with `revoked_at` populated. 4554 The caller must be the user identified by `user` and must present a 4555 first-party session (or a `full_access` access token). Returns 404 if 4556 the token does not exist or does not belong to the caller. 4557 4558 Args: 4559 user: User ID (`usr_...`) or `me` for the authenticated user. 4560 token: Access token ID (`sat_...`). Must belong to the authenticated user. 4561 4562 Returns: 4563 The revoked access token. The `revoked_at` field is populated with the time of revocation. 4564 """ 4565 return self._http.request( 4566 f"/api/v1/users/{user}/tokens/{token}", 4567 method="DELETE", 4568 response_type=SystemAccessToken, 4569 )
TokenResource(http: archastro.platform.runtime.http_client.SyncHttpClient)
4497 def list(self, user: str) -> TokenListResponse: 4498 """ 4499 List personal access tokens 4500 Returns all access tokens associated with the authenticated user, including 4501 active and revoked tokens. Tokens are returned without their raw JWT values 4502 the plaintext JWT is only available at creation time. 4503 The caller must be the user identified by `user` and must present a 4504 first-party session (or a `full_access` access token). 4505 4506 Args: 4507 user: User ID (`usr_...`) or `me` for the authenticated user. 4508 4509 Returns: 4510 Successful response 4511 """ 4512 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:
4514 def create(self, user: str, input: TokenCreateInput) -> SystemAccessToken: 4515 """ 4516 Create a personal access token 4517 Issues a new long-lived access token for the authenticated user. The raw 4518 JWT is returned in the `token` field of the response exactly once and 4519 cannot be retrieved again store it securely immediately after creation. 4520 `scopes` is optional. When omitted the token receives `full_access`. 4521 Known catalog scopes (for example `profile`) restrict the token through 4522 the same `ScopeGuard` used by OAuth. 4523 `expires_in_days` is optional and must be one of `7`, `30`, `60`, `90`, 4524 or `365`. When omitted the token lasts 30 days. Each user may hold at 4525 most 50 active tokens; exceeding that limit returns 429. 4526 The caller must be the user identified by `user` and must present a 4527 first-party session (or a `full_access` access token). A restricted 4528 access token cannot mint another token. 4529 4530 Args: 4531 user: User ID (`usr_...`) or `me` for the authenticated user. 4532 input: Request body. 4533 input.expires_in_days: Lifetime in days. One of `7`, `30`, `60`, `90`, or `365`. Defaults to `30`. 4534 input.name: Human-readable label for the token (e.g. `"Codex MCP"`). Stored as metadata only. 4535 input.scopes: Optional OAuth scopes to stamp on the token. Omit for `full_access`. 4536 4537 Returns: 4538 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. 4539 """ 4540 return self._http.request( 4541 f"/api/v1/users/{user}/tokens", 4542 method="POST", 4543 body=input, 4544 response_type=SystemAccessToken, 4545 )
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.
4547 def delete(self, user: str, token: str) -> SystemAccessToken: 4548 """ 4549 Revoke a personal access token 4550 Permanently revokes the specified access token belonging to the 4551 authenticated user. Once revoked, the token is immediately rejected by 4552 all API endpoints and cannot be reinstated. The token record is retained 4553 and returned in the response with `revoked_at` populated. 4554 The caller must be the user identified by `user` and must present a 4555 first-party session (or a `full_access` access token). Returns 404 if 4556 the token does not exist or does not belong to the caller. 4557 4558 Args: 4559 user: User ID (`usr_...`) or `me` for the authenticated user. 4560 token: Access token ID (`sat_...`). Must belong to the authenticated user. 4561 4562 Returns: 4563 The revoked access token. The `revoked_at` field is populated with the time of revocation. 4564 """ 4565 return self._http.request( 4566 f"/api/v1/users/{user}/tokens/{token}", 4567 method="DELETE", 4568 response_type=SystemAccessToken, 4569 )
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:
4572class UserResource: 4573 def __init__(self, http: SyncHttpClient): 4574 self._http = http 4575 self.integrations = IntegrationResource(http) 4576 self.ssh_keys = UserSshKeyResource(http) 4577 self.tasks = UserTaskResource(http) 4578 self.threads = UserThreadResource(http) 4579 self.tokens = TokenResource(http) 4580 4581 def me(self, *, entitlement: list[str] | None = None) -> CurrentUser: 4582 """ 4583 Retrieve the current user 4584 Returns the user associated with the authenticated session or bearer 4585 token. This is the canonical way to resolve "who am I?" after 4586 authentication. 4587 The response includes the user's profile, notification settings, and 4588 profile picture, along with the app, organization, and sandbox the 4589 token is scoped to and their display names enough to establish full 4590 session context in a single call. Unauthenticated requests return 401. 4591 4592 Args: 4593 entitlement: Entitlement catalog keys to evaluate. Supplying this expansion additionally requires `entitlements:read`. 4594 4595 Returns: 4596 The authenticated user object. 4597 """ 4598 query: dict[str, object] = {} 4599 if entitlement is not None: 4600 query["entitlement"] = entitlement 4601 return self._http.request("/api/v1/users/me", query=query, response_type=CurrentUser) 4602 4603 def get(self, user: str) -> User: 4604 """ 4605 Retrieve a user by ID 4606 Returns the user identified by `user`. The authenticated user must share 4607 an organization or at least one team with the target user; other requests 4608 are rejected with 403. 4609 A user may always retrieve their own profile with this endpoint. Use the 4610 `GET /users/me` endpoint as a convenience alias for retrieving the 4611 authenticated user without specifying an ID. 4612 4613 Args: 4614 user: User ID (`usr_...`) of the user to retrieve. 4615 4616 Returns: 4617 The requested user object. 4618 """ 4619 return self._http.request(f"/api/v1/users/{user}", response_type=User) 4620 4621 def artifacts( 4622 self, user: str, *, group_key: str | None = None, group_key_prefix: str | None = None 4623 ) -> UserArtifactsResponse: 4624 """ 4625 List a user's artifacts 4626 Returns all artifacts owned by the specified user. Artifacts represent 4627 AI-generated or user-uploaded files associated with agent sessions, 4628 threads, or sandboxes such as images, documents, and code outputs. 4629 The authenticated user must be requesting their own artifacts or must 4630 have administrative access. Attempting to list artifacts for a user 4631 the caller is not authorized to access returns 403. 4632 Results are returned in a single page without cursor pagination. Each 4633 artifact in the response reflects the state of its current version, 4634 including a short-lived signed `file_url` for direct download. 4635 4636 Args: 4637 user: User ID (`usr_...`). The authenticated user must be this user or have access to their artifacts. 4638 group_key: Case-sensitive exact group key. Mutually exclusive with group_key_prefix; null keys do not match. 4639 group_key_prefix: Nonempty case-sensitive literal prefix (percent, underscore and backslash are literal). Mutually exclusive with group_key. 4640 4641 Returns: 4642 Successful response 4643 """ 4644 query: dict[str, object] = {} 4645 if group_key is not None: 4646 query["group_key"] = group_key 4647 if group_key_prefix is not None: 4648 query["group_key_prefix"] = group_key_prefix 4649 return self._http.request( 4650 f"/api/v1/users/{user}/artifacts", 4651 query=query, 4652 response_type=UserArtifactsResponse, 4653 ) 4654 4655 def invites(self, user: str, input: UserInvitesInput) -> UserInvite: 4656 """ 4657 Create a user invite 4658 Creates a new invite for the authenticated user. The invite can optionally be 4659 scoped to a specific thread, a persona, or carry arbitrary metadata. The 4660 caller receives the new invite object at HTTP 201. 4661 The invite key is always generated server-side (192-bit URL-safe random 4662 string) and cannot be supplied by the caller. 4663 The path `:user` must match the authenticated user. If a `thread_id` is 4664 provided, the authenticated user must have permission to invite others to that 4665 thread; team threads are not supported and return an error. Supplying a 4666 `thread_id` that does not exist or that belongs to a different user returns 4667 an error. If a key collision occurs during creation the call returns a 409 4668 conflict simply retry to generate a new key. 4669 4670 Args: 4671 user: User ID (`usr_...`). Must match the authenticated user. 4672 input: Request body. 4673 input.invite: Parameters for the new invite. See the UserInviteCreateParams schema for field details. 4674 4675 Returns: 4676 The newly created invite object. 4677 """ 4678 return self._http.request( 4679 f"/api/v1/users/{user}/invites", 4680 method="POST", 4681 body=input, 4682 response_type=UserInvite, 4683 ) 4684 4685 def orgs(self, user: str) -> UserOrgsResponse: 4686 """ 4687 List organizations for a user 4688 Returns the organizations the specified user belongs to. A user can belong 4689 to at most one organization, so the `data` array contains either zero or one 4690 items. 4691 The authenticated viewer must have permission to inspect the target user. 4692 Returns an empty `data` array when the user has no organization membership. 4693 4694 Args: 4695 user: User ID (`usr_...`) whose organization membership you want to retrieve. 4696 4697 Returns: 4698 Successful response 4699 """ 4700 return self._http.request(f"/api/v1/users/{user}/orgs", response_type=UserOrgsResponse) 4701 4702 def profile(self, user: str, input: UserProfileInput) -> User: 4703 """ 4704 Update the current user's profile 4705 Updates one or more profile fields for the authenticated user. All 4706 fields are optional; omit any you do not want to change. 4707 When `profile_picture` is supplied, the image is uploaded and replaces 4708 the existing picture. The previous picture is deleted after the new one 4709 is stored. Image upload failures return 422 without modifying other 4710 profile fields. 4711 4712 Args: 4713 user: User ID (`usr_...`) or `"me"` for the authenticated user. 4714 input: Request body. 4715 input.alias: Short display alias shown in place of the full name in compact UI contexts. 4716 input.clear_full_name: Set to true to clear the optional display name. Cannot be combined with full_name. 4717 input.clear_profile_picture: Set to true to remove the current profile picture. Cannot be combined with profile_picture. 4718 input.full_name: Updated display name for the user. 4719 input.metadata: Arbitrary key-value metadata to associate with the user. Existing keys are merged; pass `null` for a key to remove it. 4720 input.profile_picture: New profile picture to upload as a base64-encoded image. Replaces any existing picture. 4721 4722 Returns: 4723 The user object with updated profile fields. 4724 """ 4725 return self._http.request( 4726 f"/api/v1/users/{user}/profile", 4727 method="PUT", 4728 body=input, 4729 response_type=User, 4730 ) 4731 4732 def task_epics( 4733 self, 4734 user: str, 4735 *, 4736 team: str | None = None, 4737 org: str | None = None, 4738 source_scope: str | None = None, 4739 source_type: str | None = None, 4740 source_id: str | None = None, 4741 top_priority: int | None = None, 4742 include_closed: bool | None = None, 4743 limit: int | None = None, 4744 after_cursor: str | None = None, 4745 ) -> UserTaskEpicsResponse: 4746 """ 4747 List an owner's epic summaries 4748 Groups tasks by their exact epic label, ordered by label. Closed tasks include cancelled tasks, but cancelled prerequisites still block. Source filters select the tasks summarized; blockers outside that selection still affect readiness. Root ranking is capped per epic and root_blockers_partial is true when that graph is truncated. No epic entity is created. 4749 4750 Args: 4751 source_scope: Exact source scope; supply all three source fields. 4752 source_type: Exact source type. 4753 source_id: Exact source ID. 4754 top_priority: Exact highest open priority, from 0 to 4. 4755 include_closed: Include epics with no non-closed tasks; defaults to false. 4756 limit: Maximum epics; defaults to 50, capped at 100. 4757 after_cursor: Opaque forward cursor from the preceding page. 4758 4759 Returns: 4760 Successful response 4761 """ 4762 query: dict[str, object] = {} 4763 if team is not None: 4764 query["team"] = team 4765 if org is not None: 4766 query["org"] = org 4767 if source_scope is not None: 4768 query["source_scope"] = source_scope 4769 if source_type is not None: 4770 query["source_type"] = source_type 4771 if source_id is not None: 4772 query["source_id"] = source_id 4773 if top_priority is not None: 4774 query["top_priority"] = top_priority 4775 if include_closed is not None: 4776 query["include_closed"] = include_closed 4777 if limit is not None: 4778 query["limit"] = limit 4779 if after_cursor is not None: 4780 query["after_cursor"] = after_cursor 4781 return self._http.request( 4782 f"/api/v1/users/{user}/task_epics", 4783 query=query, 4784 response_type=UserTaskEpicsResponse, 4785 )
UserResource(http: archastro.platform.runtime.http_client.SyncHttpClient)
def
me( self, *, entitlement: list[str] | None = None) -> archastro.platform.types.common.CurrentUser:
4581 def me(self, *, entitlement: list[str] | None = None) -> CurrentUser: 4582 """ 4583 Retrieve the current user 4584 Returns the user associated with the authenticated session or bearer 4585 token. This is the canonical way to resolve "who am I?" after 4586 authentication. 4587 The response includes the user's profile, notification settings, and 4588 profile picture, along with the app, organization, and sandbox the 4589 token is scoped to and their display names enough to establish full 4590 session context in a single call. Unauthenticated requests return 401. 4591 4592 Args: 4593 entitlement: Entitlement catalog keys to evaluate. Supplying this expansion additionally requires `entitlements:read`. 4594 4595 Returns: 4596 The authenticated user object. 4597 """ 4598 query: dict[str, object] = {} 4599 if entitlement is not None: 4600 query["entitlement"] = entitlement 4601 return self._http.request("/api/v1/users/me", query=query, response_type=CurrentUser)
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.
Arguments:
- entitlement: Entitlement catalog keys to evaluate. Supplying this expansion additionally requires
entitlements:read.
Returns:
The authenticated user object.
4603 def get(self, user: str) -> User: 4604 """ 4605 Retrieve a user by ID 4606 Returns the user identified by `user`. The authenticated user must share 4607 an organization or at least one team with the target user; other requests 4608 are rejected with 403. 4609 A user may always retrieve their own profile with this endpoint. Use the 4610 `GET /users/me` endpoint as a convenience alias for retrieving the 4611 authenticated user without specifying an ID. 4612 4613 Args: 4614 user: User ID (`usr_...`) of the user to retrieve. 4615 4616 Returns: 4617 The requested user object. 4618 """ 4619 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
an organization or at least one team with the target user; other requests
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.
def
artifacts( self, user: str, *, group_key: str | None = None, group_key_prefix: str | None = None) -> UserArtifactsResponse:
4621 def artifacts( 4622 self, user: str, *, group_key: str | None = None, group_key_prefix: str | None = None 4623 ) -> UserArtifactsResponse: 4624 """ 4625 List a user's artifacts 4626 Returns all artifacts owned by the specified user. Artifacts represent 4627 AI-generated or user-uploaded files associated with agent sessions, 4628 threads, or sandboxes such as images, documents, and code outputs. 4629 The authenticated user must be requesting their own artifacts or must 4630 have administrative access. Attempting to list artifacts for a user 4631 the caller is not authorized to access returns 403. 4632 Results are returned in a single page without cursor pagination. Each 4633 artifact in the response reflects the state of its current version, 4634 including a short-lived signed `file_url` for direct download. 4635 4636 Args: 4637 user: User ID (`usr_...`). The authenticated user must be this user or have access to their artifacts. 4638 group_key: Case-sensitive exact group key. Mutually exclusive with group_key_prefix; null keys do not match. 4639 group_key_prefix: Nonempty case-sensitive literal prefix (percent, underscore and backslash are literal). Mutually exclusive with group_key. 4640 4641 Returns: 4642 Successful response 4643 """ 4644 query: dict[str, object] = {} 4645 if group_key is not None: 4646 query["group_key"] = group_key 4647 if group_key_prefix is not None: 4648 query["group_key_prefix"] = group_key_prefix 4649 return self._http.request( 4650 f"/api/v1/users/{user}/artifacts", 4651 query=query, 4652 response_type=UserArtifactsResponse, 4653 )
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. - group_key: Case-sensitive exact group key. Mutually exclusive with group_key_prefix; null keys do not match.
- group_key_prefix: Nonempty case-sensitive literal prefix (percent, underscore and backslash are literal). Mutually exclusive with group_key.
Returns:
Successful response
def
invites( self, user: str, input: UserInvitesInput) -> archastro.platform.types.users.UserInvite:
4655 def invites(self, user: str, input: UserInvitesInput) -> UserInvite: 4656 """ 4657 Create a user invite 4658 Creates a new invite for the authenticated user. The invite can optionally be 4659 scoped to a specific thread, a persona, or carry arbitrary metadata. The 4660 caller receives the new invite object at HTTP 201. 4661 The invite key is always generated server-side (192-bit URL-safe random 4662 string) and cannot be supplied by the caller. 4663 The path `:user` must match the authenticated user. If a `thread_id` is 4664 provided, the authenticated user must have permission to invite others to that 4665 thread; team threads are not supported and return an error. Supplying a 4666 `thread_id` that does not exist or that belongs to a different user returns 4667 an error. If a key collision occurs during creation the call returns a 409 4668 conflict simply retry to generate a new key. 4669 4670 Args: 4671 user: User ID (`usr_...`). Must match the authenticated user. 4672 input: Request body. 4673 input.invite: Parameters for the new invite. See the UserInviteCreateParams schema for field details. 4674 4675 Returns: 4676 The newly created invite object. 4677 """ 4678 return self._http.request( 4679 f"/api/v1/users/{user}/invites", 4680 method="POST", 4681 body=input, 4682 response_type=UserInvite, 4683 )
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.
4685 def orgs(self, user: str) -> UserOrgsResponse: 4686 """ 4687 List organizations for a user 4688 Returns the organizations the specified user belongs to. A user can belong 4689 to at most one organization, so the `data` array contains either zero or one 4690 items. 4691 The authenticated viewer must have permission to inspect the target user. 4692 Returns an empty `data` array when the user has no organization membership. 4693 4694 Args: 4695 user: User ID (`usr_...`) whose organization membership you want to retrieve. 4696 4697 Returns: 4698 Successful response 4699 """ 4700 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
4702 def profile(self, user: str, input: UserProfileInput) -> User: 4703 """ 4704 Update the current user's profile 4705 Updates one or more profile fields for the authenticated user. All 4706 fields are optional; omit any you do not want to change. 4707 When `profile_picture` is supplied, the image is uploaded and replaces 4708 the existing picture. The previous picture is deleted after the new one 4709 is stored. Image upload failures return 422 without modifying other 4710 profile fields. 4711 4712 Args: 4713 user: User ID (`usr_...`) or `"me"` for the authenticated user. 4714 input: Request body. 4715 input.alias: Short display alias shown in place of the full name in compact UI contexts. 4716 input.clear_full_name: Set to true to clear the optional display name. Cannot be combined with full_name. 4717 input.clear_profile_picture: Set to true to remove the current profile picture. Cannot be combined with profile_picture. 4718 input.full_name: Updated display name for the user. 4719 input.metadata: Arbitrary key-value metadata to associate with the user. Existing keys are merged; pass `null` for a key to remove it. 4720 input.profile_picture: New profile picture to upload as a base64-encoded image. Replaces any existing picture. 4721 4722 Returns: 4723 The user object with updated profile fields. 4724 """ 4725 return self._http.request( 4726 f"/api/v1/users/{user}/profile", 4727 method="PUT", 4728 body=input, 4729 response_type=User, 4730 )
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.clear_full_name: Set to true to clear the optional display name. Cannot be combined with full_name.
- input.clear_profile_picture: Set to true to remove the current profile picture. Cannot be combined with profile_picture.
- 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.
def
task_epics( self, user: str, *, team: str | None = None, org: str | None = None, source_scope: str | None = None, source_type: str | None = None, source_id: str | None = None, top_priority: int | None = None, include_closed: bool | None = None, limit: int | None = None, after_cursor: str | None = None) -> UserTaskEpicsResponse:
4732 def task_epics( 4733 self, 4734 user: str, 4735 *, 4736 team: str | None = None, 4737 org: str | None = None, 4738 source_scope: str | None = None, 4739 source_type: str | None = None, 4740 source_id: str | None = None, 4741 top_priority: int | None = None, 4742 include_closed: bool | None = None, 4743 limit: int | None = None, 4744 after_cursor: str | None = None, 4745 ) -> UserTaskEpicsResponse: 4746 """ 4747 List an owner's epic summaries 4748 Groups tasks by their exact epic label, ordered by label. Closed tasks include cancelled tasks, but cancelled prerequisites still block. Source filters select the tasks summarized; blockers outside that selection still affect readiness. Root ranking is capped per epic and root_blockers_partial is true when that graph is truncated. No epic entity is created. 4749 4750 Args: 4751 source_scope: Exact source scope; supply all three source fields. 4752 source_type: Exact source type. 4753 source_id: Exact source ID. 4754 top_priority: Exact highest open priority, from 0 to 4. 4755 include_closed: Include epics with no non-closed tasks; defaults to false. 4756 limit: Maximum epics; defaults to 50, capped at 100. 4757 after_cursor: Opaque forward cursor from the preceding page. 4758 4759 Returns: 4760 Successful response 4761 """ 4762 query: dict[str, object] = {} 4763 if team is not None: 4764 query["team"] = team 4765 if org is not None: 4766 query["org"] = org 4767 if source_scope is not None: 4768 query["source_scope"] = source_scope 4769 if source_type is not None: 4770 query["source_type"] = source_type 4771 if source_id is not None: 4772 query["source_id"] = source_id 4773 if top_priority is not None: 4774 query["top_priority"] = top_priority 4775 if include_closed is not None: 4776 query["include_closed"] = include_closed 4777 if limit is not None: 4778 query["limit"] = limit 4779 if after_cursor is not None: 4780 query["after_cursor"] = after_cursor 4781 return self._http.request( 4782 f"/api/v1/users/{user}/task_epics", 4783 query=query, 4784 response_type=UserTaskEpicsResponse, 4785 )
List an owner's epic summaries Groups tasks by their exact epic label, ordered by label. Closed tasks include cancelled tasks, but cancelled prerequisites still block. Source filters select the tasks summarized; blockers outside that selection still affect readiness. Root ranking is capped per epic and root_blockers_partial is true when that graph is truncated. No epic entity is created.
Arguments:
- source_scope: Exact source scope; supply all three source fields.
- source_type: Exact source type.
- source_id: Exact source ID.
- top_priority: Exact highest open priority, from 0 to 4.
- include_closed: Include epics with no non-closed tasks; defaults to false.
- limit: Maximum epics; defaults to 50, capped at 100.
- after_cursor: Opaque forward cursor from the preceding page.
Returns:
Successful response