From 58399efd260ebe27f939472dcaea22f52cae3413 Mon Sep 17 00:00:00 2001 From: Rafael Brandao Date: Mon, 17 Aug 2026 14:13:43 -0700 Subject: [PATCH 1/2] sdk: event-subscriptions resources + agent lifecycle surface Regenerated against archastro-openapi spec/event-subscriptions-public (from firstlanding PR #10337). Adds client.event_subscriptions (list/create/get/update/delete/queue/head/claim) and client.event_subscription_deliveries (acknowledge) in async and sync variants, with the full claim contract (max_events batching, request_id idempotent retries, wait_seconds long-poll), retention settings, and the queue loss indicators. Generated contract tests included; full suite green (2676 tests). --- specs/platform-openapi.json | 17693 +++++++++++++--- src/archastro/platform/auth.py | 30 +- .../platform/channels/api_chat_channel.py | 26 +- .../platform/channels/api_tasks_channel.py | 10 +- src/archastro/platform/client.py | 6 +- src/archastro/platform/types/__init__.py | 3 +- src/archastro/platform/types/automations.py | 2 +- src/archastro/platform/types/common.py | 265 +- src/archastro/platform/types/device.py | 16 +- src/archastro/platform/types/image.py | 2 +- src/archastro/platform/types/system.py | 62 + src/archastro/platform/types/tasks.py | 18 +- src/archastro/platform/types/teams.py | 2 +- src/archastro/platform/types/threads.py | 18 +- src/archastro/platform/types/users.py | 26 +- src/archastro/platform/v1/__init__.py | 11 +- .../platform/v1/resources/__init__.py | 10 +- src/archastro/platform/v1/resources/agents.py | 6 +- .../event_subscription_deliveries.py | 66 + .../v1/resources/event_subscriptions.py | 420 + src/archastro/platform/v1/resources/oauth.py | 50 +- .../v1/resources/slack_channel_bindings.py | 124 +- .../platform/v1/resources/solutions.py | 43 +- src/archastro/platform/v1/resources/tasks.py | 149 +- src/archastro/platform/v1/resources/teams.py | 669 +- .../platform/v1/resources/threads.py | 25 +- src/archastro/platform/v1/resources/users.py | 896 +- tests/contract/v1/test_ai.py | 23 +- .../v1/test_event_subscription_deliveries.py | 140 + tests/contract/v1/test_event_subscriptions.py | 616 + tests/contract/v1/test_knowledge_sources.py | 44 +- tests/contract/v1/test_oauth.py | 65 +- .../v1/test_slack_channel_bindings.py | 142 +- tests/contract/v1/test_solutions.py | 128 +- tests/contract/v1/test_tasks.py | 249 +- tests/contract/v1/test_team_memberships.py | 23 +- tests/contract/v1/test_teams.py | 88 +- tests/contract/v1/test_threads.py | 23 +- tests/contract/v1/test_users.py | 342 +- 39 files changed, 19264 insertions(+), 3267 deletions(-) create mode 100644 src/archastro/platform/types/system.py create mode 100644 src/archastro/platform/v1/resources/event_subscription_deliveries.py create mode 100644 src/archastro/platform/v1/resources/event_subscriptions.py create mode 100644 tests/contract/v1/test_event_subscription_deliveries.py create mode 100644 tests/contract/v1/test_event_subscriptions.py diff --git a/specs/platform-openapi.json b/specs/platform-openapi.json index 289df4c..71b5c7e 100644 --- a/specs/platform-openapi.json +++ b/specs/platform-openapi.json @@ -686,7 +686,7 @@ ] }, "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", - "created_at": "2024-01-01T00:00:00Z", + "created_at": "string", "default_model": "claude-3-7-sonnet-latest", "description": "An example description.", "email": "user@example.com", @@ -834,7 +834,7 @@ }, "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "template_upgrade_available": true, - "updated_at": "2024-01-01T00:00:00Z", + "updated_at": "string", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" }, "properties": { @@ -868,6 +868,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -1018,23 +1019,25 @@ }, "created_at": { "description": "When the agent was created (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "default_model": { "description": "Default LLM model identifier used by this agent when no model is specified at runtime (e.g. `\"claude-3-7-sonnet-latest\"`).", "example": "claude-3-7-sonnet-latest", + "nullable": true, "type": "string" }, "description": { "description": "Human-readable description of what the agent does. `null` if not set.", "example": "An example description.", + "nullable": true, "type": "string" }, "email": { "description": "Email address provisioned for this agent. `null` if email delivery is not configured.", "example": "user@example.com", + "nullable": true, "type": "string" }, "id": { @@ -1045,16 +1048,19 @@ "identity": { "description": "System-level identity prompt that shapes the agent's persona and behavior.", "example": "You are a helpful assistant that answers questions about ArchAstro products.", + "nullable": true, "type": "string" }, "last_applied_template_config": { "description": "ID of the AgentTemplate config (`cfg_...`) this agent was last provisioned or updated from. `null` for manually created agents.", "example": "cfg_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "lookup_key": { "description": "Stable, user-defined identifier for this agent within the application. Unique per app.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -1072,26 +1078,31 @@ "org": { "description": "ID of the organization this agent belongs to (`org_...`). `null` if the agent is not org-scoped.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_name": { "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.", "example": "Example Name", + "nullable": true, "type": "string" }, "originator": { "description": "Free-form label identifying the source or author that created this agent (e.g. a username or pipeline name).", "example": "deploy-pipeline", + "nullable": true, "type": "string" }, "phone_number": { "description": "Phone number provisioned for this agent. `null` if SMS is not configured.", "example": "+15555550123", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the sandbox environment this agent is scoped to (`dsb_...`). `null` in production deployments.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "source_solution": { @@ -1225,6 +1236,7 @@ "virtual_path": "string" } }, + "nullable": true, "properties": { "current_solution": { "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.", @@ -1299,13 +1311,13 @@ }, "created_at": { "description": "When the Solution config was first imported (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "events": { @@ -1321,6 +1333,7 @@ "image_url": { "description": "Absolute URL of the Solution's cover image — the bundled asset the body's `image:` field names. A stable, non-expiring capability URL (like `org_logo.url`), safe to hold in caches and OpenGraph tags; it 404s if the Solution stops declaring a cover. `null` when the Solution has no cover image, and always `null` for org-scoped rows — the permanent URL is minted for system-scope (catalog) Solutions only.", "example": "https://example.com", + "nullable": true, "type": "string" }, "kind": { @@ -1331,16 +1344,19 @@ "latest_solution": { "description": "When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "latest_version": { "description": "When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", "example": "1.0.0", + "nullable": true, "type": "string" }, "lookup_key": { "description": "The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -1353,11 +1369,13 @@ "name": { "description": "Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "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.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_logo": { @@ -1371,40 +1389,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -1413,11 +1439,13 @@ "org_name": { "description": "Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_slug": { "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.", "example": "example-slug", + "nullable": true, "type": "string" }, "owners": { @@ -1433,6 +1461,7 @@ "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "screenshot_urls": { @@ -1448,11 +1477,13 @@ "solution_id": { "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.", "example": "01234567-89ab-cdef-0123-456789abcdef", + "nullable": true, "type": "string" }, "solution_version": { "description": "Semver string declared in the Solution body (e.g. `\"1.2.0\"`). `null` when the body does not declare a version.", "example": "1.2.0", + "nullable": true, "type": "string" }, "tag_keys": { @@ -1468,6 +1499,7 @@ "template_kind": { "description": "Wrapped template kind — `\"AgentTemplate\"`, `\"AutomationTemplate\"`, `\"AgentRoutineTemplate\"`, `\"AgentToolTemplate\"`, `\"AgentComputerTemplate\"`, or `\"SolutionTemplateRef\"` for ref-mode bundles.", "example": "AgentTemplate", + "nullable": true, "type": "string" }, "templates": { @@ -1500,6 +1532,7 @@ "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "details": { @@ -1507,6 +1540,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -1531,12 +1565,13 @@ }, "properties": { "automation_type": { - "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`).", + "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", "example": "string", + "nullable": true, "type": "string" }, "invoke_contract": { - "description": "Schema-driven payload and participant inputs for an invoked automation. Used by installation clients to collect locked prefills before provisioning.", + "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.", "example": { "input_schema": {}, "participants": [ @@ -1552,10 +1587,12 @@ "payload": {} } }, + "nullable": true, "properties": { "input_schema": { "description": "JSON Schema validated against the whole invoke payload, from the automation's `input_schema_config`. `null` when none is configured.", "example": {}, + "nullable": true, "type": "object" }, "participants": { @@ -1576,10 +1613,12 @@ "required": true, "type": "agent_user" }, + "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", "example": "An example description.", + "nullable": true, "type": "string" }, "name": { @@ -1605,6 +1644,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -1653,11 +1693,13 @@ "display_name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "id": { "description": "Template config ID (`cfg_...`). `null` for inline-only templates.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "kind": { @@ -1668,21 +1710,25 @@ "lookup_key": { "description": "Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", "example": "string", + "nullable": true, "type": "string" }, "name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "virtual_path": { "description": "Stable virtual path assigned to the template config. `null` when no virtual path was set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -1695,8 +1741,7 @@ }, "updated_at": { "description": "When the Solution config was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "upgrade_available": { @@ -1707,6 +1752,7 @@ "virtual_path": { "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.", "example": "string", + "nullable": true, "type": "string" } }, @@ -1792,13 +1838,13 @@ }, "created_at": { "description": "When the Solution config was first imported (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "events": { @@ -1814,6 +1860,7 @@ "image_url": { "description": "Absolute URL of the Solution's cover image — the bundled asset the body's `image:` field names. A stable, non-expiring capability URL (like `org_logo.url`), safe to hold in caches and OpenGraph tags; it 404s if the Solution stops declaring a cover. `null` when the Solution has no cover image, and always `null` for org-scoped rows — the permanent URL is minted for system-scope (catalog) Solutions only.", "example": "https://example.com", + "nullable": true, "type": "string" }, "kind": { @@ -1824,16 +1871,19 @@ "latest_solution": { "description": "When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "latest_version": { "description": "When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", "example": "1.0.0", + "nullable": true, "type": "string" }, "lookup_key": { "description": "The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -1846,11 +1896,13 @@ "name": { "description": "Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "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.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_logo": { @@ -1864,40 +1916,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -1906,11 +1966,13 @@ "org_name": { "description": "Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_slug": { "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.", "example": "example-slug", + "nullable": true, "type": "string" }, "owners": { @@ -1926,6 +1988,7 @@ "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "screenshot_urls": { @@ -1941,11 +2004,13 @@ "solution_id": { "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.", "example": "01234567-89ab-cdef-0123-456789abcdef", + "nullable": true, "type": "string" }, "solution_version": { "description": "Semver string declared in the Solution body (e.g. `\"1.2.0\"`). `null` when the body does not declare a version.", "example": "1.2.0", + "nullable": true, "type": "string" }, "tag_keys": { @@ -1961,6 +2026,7 @@ "template_kind": { "description": "Wrapped template kind — `\"AgentTemplate\"`, `\"AutomationTemplate\"`, `\"AgentRoutineTemplate\"`, `\"AgentToolTemplate\"`, `\"AgentComputerTemplate\"`, or `\"SolutionTemplateRef\"` for ref-mode bundles.", "example": "AgentTemplate", + "nullable": true, "type": "string" }, "templates": { @@ -1993,6 +2059,7 @@ "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "details": { @@ -2000,6 +2067,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -2024,12 +2092,13 @@ }, "properties": { "automation_type": { - "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`).", + "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", "example": "string", + "nullable": true, "type": "string" }, "invoke_contract": { - "description": "Schema-driven payload and participant inputs for an invoked automation. Used by installation clients to collect locked prefills before provisioning.", + "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.", "example": { "input_schema": {}, "participants": [ @@ -2045,10 +2114,12 @@ "payload": {} } }, + "nullable": true, "properties": { "input_schema": { "description": "JSON Schema validated against the whole invoke payload, from the automation's `input_schema_config`. `null` when none is configured.", "example": {}, + "nullable": true, "type": "object" }, "participants": { @@ -2069,10 +2140,12 @@ "required": true, "type": "agent_user" }, + "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", "example": "An example description.", + "nullable": true, "type": "string" }, "name": { @@ -2098,6 +2171,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -2146,11 +2220,13 @@ "display_name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "id": { "description": "Template config ID (`cfg_...`). `null` for inline-only templates.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "kind": { @@ -2161,21 +2237,25 @@ "lookup_key": { "description": "Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", "example": "string", + "nullable": true, "type": "string" }, "name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "virtual_path": { "description": "Stable virtual path assigned to the template config. `null` when no virtual path was set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -2188,8 +2268,7 @@ }, "updated_at": { "description": "When the Solution config was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "upgrade_available": { @@ -2200,6 +2279,7 @@ "virtual_path": { "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.", "example": "string", + "nullable": true, "type": "string" } }, @@ -2235,11 +2315,13 @@ "description": { "description": "Description of the template from the config body. `null` if the current version has no `description` field.", "example": "An example description.", + "nullable": true, "type": "string" }, "display_name": { "description": "Human-readable display name from the config body. `null` if the current version has no `display_name` field.", "example": "Example Name", + "nullable": true, "type": "string" }, "id": { @@ -2255,11 +2337,13 @@ "lookup_key": { "description": "Stable lookup key assigned to this template config. `null` if no lookup key is set.", "example": "string", + "nullable": true, "type": "string" }, "name": { "description": "Template name as stored in the config body. `null` if the current version has no `name` field.", "example": "Example Name", + "nullable": true, "type": "string" }, "updated_at": { @@ -2271,6 +2355,7 @@ "virtual_path": { "description": "Virtual filesystem path for this template config. `null` if not set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -2290,22 +2375,24 @@ "team": { "description": "ID of the team that owns this agent (`tem_...`). `null` if the agent is not team-scoped.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "template_upgrade_available": { "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`).", "example": true, + "nullable": true, "type": "boolean" }, "updated_at": { "description": "When the agent was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "user": { "description": "ID of the user that owns this agent (`usr_...`). `null` if the agent is not user-scoped.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" } }, @@ -2428,6 +2515,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -2438,6 +2530,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" }, @@ -2445,21 +2538,55 @@ "alias": { "description": "Short handle or alias for the user. `null` if not set.", "example": "jdoe", + "nullable": true, "type": "string" }, "app": { "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.", "example": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "app_name": { "description": "Display name of the user's app. `null` when the app association was not preloaded by the caller.", "example": "Example Name", + "nullable": true, + "type": "string" + }, + "created_by_agent_user": { + "description": "Agent user that created this account (`usr_...`). `null` unless an agent created it.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_developer": { + "description": "Developer account that created this user (`dva_...`). `null` unless created via a developer token.", + "example": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_org": { + "description": "Org of the principal that created this user (`org_...`). `null` on legacy rows.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_team": { + "description": "Team that created this user (`tem_...`). `null` unless created as a team.", + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_user": { + "description": "User who created this account (`usr_...`). `null` on self-signup or legacy rows.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "email": { "description": "Email address of the user.", "example": "user@example.com", + "nullable": true, "type": "string" }, "id": { @@ -2482,31 +2609,43 @@ "name": { "description": "Full display name of the user. `null` if the user has not set a name.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "description": "ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_name": { "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.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_role": { "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.", "example": "member", + "nullable": true, + "type": "string" + }, + "org_slug": { + "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.", + "example": "example-slug", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "sandbox_name": { "description": "Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.", "example": "Example Name", + "nullable": true, "type": "string" } }, @@ -2608,21 +2747,38 @@ "alias": { "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", "example": "alice", + "nullable": true, "type": "string" }, "id": { "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "nullable": true, "type": "string" }, "name": { "description": "Display name of the actor shown in the UI. `null` if no name is set.", "example": "Example Name", + "nullable": true, "type": "string" }, "profile_picture": { - "$ref": "#/components/schemas/ImageSource", - "description": "Profile picture for the actor. `null` if the actor has no profile picture." + "allOf": [ + { + "$ref": "#/components/schemas/ImageSource" + } + ], + "description": "Profile picture for the actor. `null` if the actor has no profile picture.", + "example": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + }, + "nullable": true } }, "type": "object" @@ -2659,7 +2815,7 @@ ] }, "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", - "created_at": "2024-01-01T00:00:00Z", + "created_at": "string", "default_model": "claude-3-7-sonnet-latest", "description": "An example description.", "email": "user@example.com", @@ -2807,13 +2963,46 @@ }, "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "template_upgrade_available": true, - "updated_at": "2024-01-01T00:00:00Z", + "updated_at": "string", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" }, "properties": { "acl": { - "$ref": "#/components/schemas/Acl", - "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." + "allOf": [ + { + "$ref": "#/components/schemas/Acl" + } + ], + "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.", + "example": { + "add": [ + { + "actions": [ + "read", + "write" + ], + "principal": "string", + "principal_type": "user" + } + ], + "grants": [ + { + "actions": [ + "read", + "write" + ], + "principal": "string", + "principal_type": "user" + } + ], + "remove": [ + { + "principal": "string", + "principal_type": "user" + } + ] + }, + "nullable": true }, "app": { "description": "ID of the application that owns this agent (`dap_...`).", @@ -2822,23 +3011,25 @@ }, "created_at": { "description": "When the agent was created (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "default_model": { "description": "Default LLM model identifier used by this agent when no model is specified at runtime (e.g. `\"claude-3-7-sonnet-latest\"`).", "example": "claude-3-7-sonnet-latest", + "nullable": true, "type": "string" }, "description": { "description": "Human-readable description of what the agent does. `null` if not set.", "example": "An example description.", + "nullable": true, "type": "string" }, "email": { "description": "Email address provisioned for this agent. `null` if email delivery is not configured.", "example": "user@example.com", + "nullable": true, "type": "string" }, "id": { @@ -2849,16 +3040,19 @@ "identity": { "description": "System-level identity prompt that shapes the agent's persona and behavior.", "example": "You are a helpful assistant that answers questions about ArchAstro products.", + "nullable": true, "type": "string" }, "last_applied_template_config": { "description": "ID of the AgentTemplate config (`cfg_...`) this agent was last provisioned or updated from. `null` for manually created agents.", "example": "cfg_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "lookup_key": { "description": "Stable, user-defined identifier for this agent within the application. Unique per app.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -2876,51 +3070,192 @@ "org": { "description": "ID of the organization this agent belongs to (`org_...`). `null` if the agent is not org-scoped.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_name": { "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.", "example": "Example Name", + "nullable": true, "type": "string" }, "originator": { "description": "Free-form label identifying the source or author that created this agent (e.g. a username or pipeline name).", "example": "deploy-pipeline", + "nullable": true, "type": "string" }, "phone_number": { "description": "Phone number provisioned for this agent. `null` if SMS is not configured.", "example": "+15555550123", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the sandbox environment this agent is scoped to (`dsb_...`). `null` in production deployments.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "source_solution": { - "$ref": "#/components/schemas/AgentSourceSolution", - "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." + "allOf": [ + { + "$ref": "#/components/schemas/AgentSourceSolution" + } + ], + "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.", + "example": { + "current_solution": { + "category_keys": [ + "string" + ], + "created_at": "2024-01-01T00:00:00Z", + "description": "An example description.", + "events": {}, + "id": "id_0aBcDeFgHiJkLmNoPqRsTu", + "image_url": "https://example.com", + "kind": "Solution", + "latest_solution": "id_0aBcDeFgHiJkLmNoPqRsTu", + "latest_version": "1.0.0", + "lookup_key": "string", + "metadata": { + "key": "value" + }, + "name": "Example Name", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "org_logo": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + }, + "org_name": "Example Name", + "org_slug": "example-slug", + "owners": [ + "string" + ], + "readme_url": "https://example.com", + "screenshot_urls": [ + "https://example.com" + ], + "solution_id": "01234567-89ab-cdef-0123-456789abcdef", + "solution_version": "1.2.0", + "tag_keys": [ + "string" + ], + "template_kind": "AgentTemplate", + "templates": [ + { + "description": "An example description.", + "display_name": "Example Name", + "id": "id_0aBcDeFgHiJkLmNoPqRsTu", + "kind": "AgentTemplate", + "lookup_key": "string", + "name": "Example Name", + "readme_url": "https://example.com", + "virtual_path": "string" + } + ], + "updated_at": "2024-01-01T00:00:00Z", + "upgrade_available": true, + "virtual_path": "string" + }, + "solution": { + "category_keys": [ + "string" + ], + "created_at": "2024-01-01T00:00:00Z", + "description": "An example description.", + "events": {}, + "id": "id_0aBcDeFgHiJkLmNoPqRsTu", + "image_url": "https://example.com", + "kind": "Solution", + "latest_solution": "id_0aBcDeFgHiJkLmNoPqRsTu", + "latest_version": "1.0.0", + "lookup_key": "string", + "metadata": { + "key": "value" + }, + "name": "Example Name", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "org_logo": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + }, + "org_name": "Example Name", + "org_slug": "example-slug", + "owners": [ + "string" + ], + "readme_url": "https://example.com", + "screenshot_urls": [ + "https://example.com" + ], + "solution_id": "01234567-89ab-cdef-0123-456789abcdef", + "solution_version": "1.2.0", + "tag_keys": [ + "string" + ], + "template_kind": "AgentTemplate", + "templates": [ + { + "description": "An example description.", + "display_name": "Example Name", + "id": "id_0aBcDeFgHiJkLmNoPqRsTu", + "kind": "AgentTemplate", + "lookup_key": "string", + "name": "Example Name", + "readme_url": "https://example.com", + "virtual_path": "string" + } + ], + "updated_at": "2024-01-01T00:00:00Z", + "upgrade_available": true, + "virtual_path": "string" + }, + "template": { + "created_at": "2024-01-01T00:00:00Z", + "description": "An example description.", + "display_name": "Example Name", + "id": "id_0aBcDeFgHiJkLmNoPqRsTu", + "kind": "agent_tool_template", + "lookup_key": "string", + "name": "Example Name", + "updated_at": "2024-01-01T00:00:00Z", + "virtual_path": "string" + } + }, + "nullable": true }, "team": { "description": "ID of the team that owns this agent (`tem_...`). `null` if the agent is not team-scoped.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "template_upgrade_available": { "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`).", "example": true, + "nullable": true, "type": "boolean" }, "updated_at": { "description": "When the agent was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "user": { "description": "ID of the user that owns this agent (`usr_...`). `null` if the agent is not user-scoped.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" } }, @@ -3114,7 +3449,7 @@ ] }, "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", - "created_at": "2024-01-01T00:00:00Z", + "created_at": "string", "default_model": "claude-3-5-sonnet-20241022", "email": "user@example.com", "id": "agi_0aBcDeFgHiJkLmNoPqRsTu", @@ -3137,13 +3472,46 @@ "phone_number": "+15555550123", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", - "updated_at": "2024-01-01T00:00:00Z", + "updated_at": "string", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" }, "properties": { "acl": { - "$ref": "#/components/schemas/Acl", - "description": "Access control list governing who can interact with this agent. Contains a `grants` array where each entry specifies `principal_type`, `principal`, and `actions`. `null` when no ACL restrictions are applied." + "allOf": [ + { + "$ref": "#/components/schemas/Acl" + } + ], + "description": "Access control list governing who can interact with this agent. Contains a `grants` array where each entry specifies `principal_type`, `principal`, and `actions`. `null` when no ACL restrictions are applied.", + "example": { + "add": [ + { + "actions": [ + "read", + "write" + ], + "principal": "string", + "principal_type": "user" + } + ], + "grants": [ + { + "actions": [ + "read", + "write" + ], + "principal": "string", + "principal_type": "user" + } + ], + "remove": [ + { + "principal": "string", + "principal_type": "user" + } + ] + }, + "nullable": true }, "app": { "description": "ID of the app this agent belongs to (`dap_...`).", @@ -3152,18 +3520,19 @@ }, "created_at": { "description": "When the agent was created (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "default_model": { "description": "Default AI model the agent uses when no model is specified at runtime, e.g. `\"claude-3-5-sonnet-20241022\"`. `null` if not configured.", "example": "claude-3-5-sonnet-20241022", + "nullable": true, "type": "string" }, "email": { "description": "Email address assigned to this agent for inbound email handling. `null` if not configured.", "example": "user@example.com", + "nullable": true, "type": "string" }, "id": { @@ -3174,6 +3543,7 @@ "identity": { "description": "System prompt or persona description that shapes the agent's behavior. `null` if not set.", "example": "You are a helpful assistant.", + "nullable": true, "type": "string" }, "installed_configs": { @@ -3186,6 +3556,7 @@ "lookup_key": { "description": "Unique, stable identifier for the agent within its app. `null` if not set.", "example": "my-agent", + "nullable": true, "type": "string" }, "metadata": { @@ -3203,37 +3574,42 @@ "org": { "description": "ID of the organization this agent belongs to (`org_...`). `null` for agents outside an org.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "originator": { "description": "Free-form label identifying the source or author of the agent, e.g. a username or service name. `null` if not set.", "example": "my-service", + "nullable": true, "type": "string" }, "phone_number": { "description": "Phone number assigned to this agent for inbound SMS or voice handling. `null` if not configured.", "example": "+15555550123", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the sandbox environment this agent is scoped to (`sbx_...`). `null` for agents not scoped to a sandbox.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "team": { "description": "ID of the team that owns this agent (`tea_...`). `null` if owned by a user rather than a team.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "updated_at": { "description": "When the agent record was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "user": { "description": "ID of the user that owns this agent (`usr_...`). `null` if owned by a team.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" } }, @@ -6182,21 +6558,25 @@ "content_type": { "description": "MIME type of the attached file, e.g. `\"image/png\"` or `\"application/pdf\"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.", "example": "application/json", + "nullable": true, "type": "string" }, "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "filename": { "description": "Original filename of the attached file, e.g. `\"report.pdf\"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.", "example": "string", + "nullable": true, "type": "string" }, "height": { "description": "Height in pixels of the media item. Present on `media` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "id": { @@ -6207,40 +6587,59 @@ "image_height": { "description": "Height in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "image_source": { - "$ref": "#/components/schemas/ImageSource", - "description": "Image source metadata for inline rendering. Present on `file`, `scraped_link`, `artifact`, and `media` types when the content is an image. `null` otherwise." + "allOf": [ + { + "$ref": "#/components/schemas/ImageSource" + } + ], + "description": "Image source metadata for inline rendering. Present on `file`, `scraped_link`, `artifact`, and `media` types when the content is an image. `null` otherwise.", + "example": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + }, + "nullable": true }, "image_url": { "description": "URL of the preview image extracted from the scraped page. Present on `scraped_link` type only. `null` otherwise.", "example": "https://example.com", + "nullable": true, "type": "string" }, "image_width": { "description": "Width in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "media_type": { - "description": "The media category, e.g. `\"video\"` or `\"audio\"`. Present on `media` type only. `null` otherwise.", + "description": "The media category, e.g. `\"video\"` or `\"audio\"`. Present on `media` type only; omitted otherwise.", "example": "application/json", "type": "string" }, "name": { "description": "Display name of the media item. Present on `media` type only. `null` otherwise.", "example": "Example Name", + "nullable": true, "type": "string" }, "object": { - "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`. `null` on other types.", + "description": "The full embedded object payload. For `task` type, contains the task record. For `action` type, contains the action definition. For `chart` type, contains the chart with its inline `spec`. Omitted on other types.", "example": {}, "type": "object" }, "title": { "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.", "example": "Example Title", + "nullable": true, "type": "string" }, "type": { @@ -6251,10 +6650,11 @@ "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "variants": { - "description": "Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only. `null` otherwise.", + "description": "Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only; omitted otherwise.", "items": { "$ref": "#/components/schemas/MediaVariant" }, @@ -6263,11 +6663,13 @@ "version": { "description": "Version number of the attached artifact at the time of attachment. Present on `artifact` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "width": { "description": "Width in pixels of the media item. Present on `media` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" } }, @@ -6291,6 +6693,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -6301,6 +6708,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -6362,6 +6770,7 @@ "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", "example": "An example description.", + "nullable": true, "type": "string" }, "name": { @@ -7071,6 +7480,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -7081,6 +7495,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -7220,7 +7635,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" } ], @@ -7422,7 +7837,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "participant": [ @@ -7433,6 +7848,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -7443,6 +7863,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -7648,7 +8069,7 @@ ], "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "title": "Example Title", - "ttl": 3600, + "ttl": "2026-08-15T12:00:00", "unread_count": 5, "updated_at": "2024-01-01T00:00:00Z", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", @@ -7852,7 +8273,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "participant": [ @@ -7863,6 +8284,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -7873,6 +8299,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -8078,7 +8505,7 @@ ], "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "title": "Example Title", - "ttl": 3600, + "ttl": "2026-08-15T12:00:00", "unread_count": 5, "updated_at": "2024-01-01T00:00:00Z", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", @@ -8481,6 +8908,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -8491,6 +8923,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -8630,7 +9063,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" } ], @@ -8832,7 +9265,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "participant": [ @@ -8843,6 +9276,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -8853,6 +9291,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -9058,7 +9497,7 @@ ], "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "title": "Example Title", - "ttl": 3600, + "ttl": "2026-08-15T12:00:00", "unread_count": 5, "updated_at": "2024-01-01T00:00:00Z", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", @@ -9284,6 +9723,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -9294,6 +9738,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -9460,7 +9905,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" } ] @@ -9615,7 +10060,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" } }, @@ -10006,6 +10451,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -10016,6 +10466,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -10155,7 +10606,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" } ], @@ -10357,7 +10808,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "participant": [ @@ -10368,6 +10819,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -10378,6 +10834,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -10583,7 +11040,7 @@ ], "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "title": "Example Title", - "ttl": 3600, + "ttl": "2026-08-15T12:00:00", "unread_count": 5, "updated_at": "2024-01-01T00:00:00Z", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", @@ -11670,6 +12127,45 @@ }, "type": "object" }, + "DeviceAuthorizationDetailsResponse": { + "description": "User-visible details for a pending OAuth 2.0 device authorization.", + "example": { + "client_name": "Example Name", + "expires_at": "2024-01-01T00:00:00Z", + "scopes": [ + "string" + ] + }, + "properties": { + "client_name": { + "description": "Name of the client requesting authorization.", + "example": "Example Name", + "type": "string" + }, + "expires_at": { + "description": "Expiration time for the pending device authorization.", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "type": "string" + }, + "scopes": { + "description": "Scopes the client is requesting.", + "example": [ + "string" + ], + "items": { + "type": "string" + }, + "type": "array" + } + }, + "required": [ + "client_name", + "scopes", + "expires_at" + ], + "type": "object" + }, "DeviceAuthorizationResponse": { "description": "The initial response from an OAuth 2.0 Device Authorization Grant request, containing the codes and URIs needed to complete device authentication.", "example": { @@ -11739,342 +12235,901 @@ ], "type": "object" }, - "Extraction": { - "description": "An extraction job: yields text from a document or website into a destination namespace, without committing knowledge to an agent.", + "DomainEvent": { + "description": "A domain event with stable attribution fields and an event-specific payload.", "example": { "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", - "byte_count": 1, "created_at": "2024-01-01T00:00:00Z", - "destination": {}, - "failure_reason": "fetch_failed", - "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", - "id": "ext_0aBcDeFgHiJkLmNoPqRsTu", - "kind": "document", + "event_name": "Example Name", + "id": "string", + "idempotency_key": "string", "org": "org_0aBcDeFgHiJkLmNoPqRsTu", - "output_count": 1, - "outputs": [ - { - "created_at": "2024-01-01T00:00:00Z", - "file": { - "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", - "content_type": "application/json", - "created_at": "2024-01-01T00:00:00Z", - "filename": "document.pdf", - "id": "fil_0aBcDeFgHiJkLmNoPqRsTu", - "image_source": { - "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", - "height": 600, - "media": "med_0aBcDeFgHiJkLmNoPqRsTu", - "mime_type": "application/json", - "refresh_url": "https://example.com", - "url": "https://example.com", - "width": 800 - }, - "org": "org_0aBcDeFgHiJkLmNoPqRsTu", - "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", - "share_url": "https://example.com", - "size": 1024, - "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", - "updated_at": "2024-01-01T00:00:00Z", - "url": "https://example.com", - "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" - }, - "id": "exo_0aBcDeFgHiJkLmNoPqRsTu", - "ordinal": 1, - "source_url": "https://example.com", - "state": "done" - } - ], - "state": "pending", - "updated_at": "2024-01-01T00:00:00Z", - "url": "https://example.com" + "payload": {}, + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" }, "properties": { "agent": { - "description": "Owning agent (`agt_...`); `null` when not agent-scoped.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", "type": "string" }, - "byte_count": { - "description": "Total bytes across produced storage files (a derived aggregate).", - "example": 1, - "type": "integer" - }, "created_at": { - "description": "When the extraction was created (ISO 8601).", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, - "destination": { - "description": "Where outputs were written: `{ kind, path_prefix }`.", - "example": {}, - "type": "object" - }, - "failure_reason": { - "description": "Failure category when `state` is `failed`; `null` otherwise.", - "enum": [ - "fetch_failed", - "unsupported_content", - "extraction_failed", - "timeout", - "internal_error" - ], - "example": "fetch_failed", - "type": "string" - }, - "file": { - "description": "Source file (`fil_...`) for document extraction; `null` for link/site.", - "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "event_name": { + "example": "Example Name", "type": "string" }, "id": { - "description": "Extraction ID (`ext_...`).", - "example": "ext_0aBcDeFgHiJkLmNoPqRsTu", + "example": "string", "type": "string" }, - "kind": { - "description": "What is being extracted.", - "enum": [ - "document", - "link", - "site" - ], - "example": "document", + "idempotency_key": { + "example": "string", "type": "string" }, "org": { - "description": "Owning organization (`org_...`).", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", "type": "string" }, - "output_count": { - "description": "Number of produced output files (a derived aggregate).", - "example": 1, - "type": "integer" - }, - "outputs": { - "description": "Produced output files; populated only when the association is preloaded.", - "items": { - "$ref": "#/components/schemas/ExtractionOutput" - }, - "type": "array" + "payload": { + "description": "Opaque event-specific JSON. Use event_name to select the expected payload schema.", + "example": {}, + "type": "object" }, - "state": { - "description": "Lifecycle state of the extraction job.", - "enum": [ - "pending", - "running", - "done", - "failed" - ], - "example": "pending", + "sandbox": { + "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "type": "string" }, - "updated_at": { - "description": "When the extraction was last updated (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "team": { + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", "type": "string" }, - "url": { - "description": "Source URL for link/site extraction; `null` for document.", - "example": "https://example.com", + "user": { + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", "type": "string" } }, "required": [ - "id" + "id", + "event_name", + "payload", + "created_at" ], "type": "object" }, - "ExtractionOutput": { - "description": "A produced file tracked by an extraction. Type, size, and URL live on the file it points at.", + "EventSubscription": { + "description": "An app-scoped subscription to exact domain-event names.", "example": { + "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "available_count": 1, "created_at": "2024-01-01T00:00:00Z", - "file": { - "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", - "content_type": "application/json", - "created_at": "2024-01-01T00:00:00Z", - "filename": "document.pdf", - "id": "fil_0aBcDeFgHiJkLmNoPqRsTu", - "image_source": { - "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", - "height": 600, - "media": "med_0aBcDeFgHiJkLmNoPqRsTu", - "mime_type": "application/json", - "refresh_url": "https://example.com", - "url": "https://example.com", - "width": 800 - }, - "org": "org_0aBcDeFgHiJkLmNoPqRsTu", - "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", - "share_url": "https://example.com", - "size": 1024, - "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", - "updated_at": "2024-01-01T00:00:00Z", - "url": "https://example.com", - "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" - }, - "id": "exo_0aBcDeFgHiJkLmNoPqRsTu", - "ordinal": 1, - "source_url": "https://example.com", - "state": "done" + "dropped_events_total": 1, + "dropped_through_position": 1, + "event_names": [ + "Example Name" + ], + "id": "string", + "last_overflow_at": "2024-01-01T00:00:00Z", + "leased_count": 1, + "max_pending_events": 1, + "name": "Example Name", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "queue_epoch": 1, + "retention_seconds": 1, + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "status": "active", + "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "updated_at": "2024-01-01T00:00:00Z", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "visibility_timeout_seconds": 1 }, "properties": { + "agent": { + "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "available_count": { + "example": 1, + "type": "integer" + }, "created_at": { - "description": "When this output was produced (ISO 8601).", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, - "file": { - "$ref": "#/components/schemas/StorageFile", - "description": "The produced file. For a config destination this is the `Storage.File` backing the versioned config row; type, size, and URL live here." + "dropped_events_total": { + "example": 1, + "type": "integer" + }, + "dropped_through_position": { + "example": 1, + "type": "integer" + }, + "event_names": { + "example": [ + "Example Name" + ], + "items": { + "type": "string" + }, + "type": "array" }, "id": { - "description": "Output ID (`exo_...`).", - "example": "exo_0aBcDeFgHiJkLmNoPqRsTu", + "example": "string", "type": "string" }, - "ordinal": { - "description": "Position of this output within the extraction's output set.", + "last_overflow_at": { + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "type": "string" + }, + "leased_count": { "example": 1, "type": "integer" }, - "source_url": { - "description": "The crawled page path or document path this output came from.", - "example": "https://example.com", + "max_pending_events": { + "example": 1, + "type": "integer" + }, + "name": { + "example": "Example Name", "type": "string" }, - "state": { - "description": "Output state.", + "org": { + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "queue_epoch": { + "example": 1, + "type": "integer" + }, + "retention_seconds": { + "example": 1, + "type": "integer" + }, + "sandbox": { + "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "status": { "enum": [ - "done", - "failed" + "active", + "paused" ], - "example": "done", + "example": "active", + "type": "string" + }, + "team": { + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", "type": "string" + }, + "updated_at": { + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "type": "string" + }, + "user": { + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "visibility_timeout_seconds": { + "example": 1, + "type": "integer" } }, "required": [ - "id" + "id", + "name", + "event_names", + "status", + "max_pending_events", + "visibility_timeout_seconds", + "retention_seconds", + "available_count", + "leased_count", + "queue_epoch", + "dropped_events_total", + "dropped_through_position", + "created_at", + "updated_at" ], "type": "object" }, - "HealthActionListResponse": { - "description": "List response containing agent health actions for a given agent or organization.", + "EventSubscriptionClaim": { + "description": "Result of atomically claiming the head delivery.", "example": { "data": [ { - "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", - "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", - "created_at": "2024-01-01T00:00:00Z", - "depends_on": [ - "string" - ], - "description": "An example description.", - "id": "aha_0aBcDeFgHiJkLmNoPqRsTu", - "kind": "env_var", - "last_verified_at": "2024-01-01T00:00:00Z", - "last_verifier_message": "string", - "org": "org_0aBcDeFgHiJkLmNoPqRsTu", - "params": { - "key": "value" + "delivery_id": "string", + "event": { + "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "created_at": "2024-01-01T00:00:00Z", + "event_name": "Example Name", + "id": "string", + "idempotency_key": "string", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "payload": {}, + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" }, - "required": true, - "sort_order": 1, - "source": "setup", - "status": "pending", - "title": "Example Title", - "updated_at": "2024-01-01T00:00:00Z", - "verify_config": {} + "lease_expires_at": "2024-01-01T00:00:00Z", + "receipt_handle": "string", + "receive_count": 1, + "sequence": 1 } - ] + ], + "dropped_events_total": 1, + "dropped_through_position": 1, + "has_more": true, + "queue_epoch": 1 }, "properties": { "data": { - "description": "Array of agent health action objects representing setup checklist items and probe-detected issues.", "items": { - "$ref": "#/components/schemas/AgentHealthAction" + "$ref": "#/components/schemas/EventSubscriptionDelivery" }, "type": "array" + }, + "dropped_events_total": { + "example": 1, + "type": "integer" + }, + "dropped_through_position": { + "example": 1, + "type": "integer" + }, + "has_more": { + "example": true, + "type": "boolean" + }, + "queue_epoch": { + "example": 1, + "type": "integer" } }, "required": [ - "data" + "data", + "has_more", + "queue_epoch", + "dropped_events_total", + "dropped_through_position" ], "type": "object" }, - "ImageSource": { - "description": "Resolved metadata for an image, including its delivery URL, dimensions, and optional references to the underlying storage file or media record.", + "EventSubscriptionDelivery": { + "description": "A domain event leased from a subscription queue.", "example": { - "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", - "height": 600, - "media": "med_0aBcDeFgHiJkLmNoPqRsTu", - "mime_type": "application/json", - "refresh_url": "https://example.com", - "url": "https://example.com", - "width": 800 + "delivery_id": "string", + "event": { + "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "created_at": "2024-01-01T00:00:00Z", + "event_name": "Example Name", + "id": "string", + "idempotency_key": "string", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "payload": {}, + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" + }, + "lease_expires_at": "2024-01-01T00:00:00Z", + "receipt_handle": "string", + "receive_count": 1, + "sequence": 1 }, "properties": { - "file": { - "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", - "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "delivery_id": { + "example": "string", "type": "string" }, - "height": { - "description": "Height of the image in pixels. `null` if not known.", - "example": 600, - "type": "integer" - }, - "media": { - "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", - "example": "med_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" + "event": { + "$ref": "#/components/schemas/DomainEvent" }, - "mime_type": { - "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", - "example": "application/json", + "lease_expires_at": { + "example": "2024-01-01T00:00:00Z", + "format": "date-time", "type": "string" }, - "refresh_url": { - "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.", - "example": "https://example.com", + "receipt_handle": { + "example": "string", "type": "string" }, - "url": { - "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.", - "example": "https://example.com", - "type": "string" + "receive_count": { + "example": 1, + "type": "integer" }, - "width": { - "description": "Width of the image in pixels. `null` if not known.", - "example": 800, + "sequence": { + "example": 1, "type": "integer" } }, + "required": [ + "delivery_id", + "sequence", + "receipt_handle", + "lease_expires_at", + "receive_count", + "event" + ], "type": "object" }, - "Installation": { - "description": "An installation representing a connection between an agent and an external service or enablement channel. Tracks configuration, lifecycle state, and any bound integration.", + "EventSubscriptionHead": { + "description": "A non-reserving view of the queue head.", "example": { - "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", - "config": {}, - "created_at": "2024-01-01T00:00:00Z", - "id": "cin_0aBcDeFgHiJkLmNoPqRsTu", - "kind": "enablement/github_app", - "lookup_key": "string", - "shared_integration": "int_0aBcDeFgHiJkLmNoPqRsTu", - "state": "active", - "status_payload": {}, - "updated_at": "2024-01-01T00:00:00Z" - }, - "properties": { - "agent": { - "description": "ID of the agent that owns this installation (`agi_...`). `null` if the installation has no agent owner.", - "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" + "data": { + "delivery_id": "string", + "event": { + "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "created_at": "2024-01-01T00:00:00Z", + "event_name": "Example Name", + "id": "string", + "idempotency_key": "string", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "payload": {}, + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" + }, + "lease_expires_at": "2024-01-01T00:00:00Z", + "receive_count": 1, + "sequence": 1, + "state": "available" + } + }, + "properties": { + "data": { + "$ref": "#/components/schemas/EventSubscriptionQueueEntry" + } + }, + "type": "object" + }, + "EventSubscriptionPage": { + "description": "A page of domain-event subscriptions.", + "example": { + "data": [ + { + "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "available_count": 1, + "created_at": "2024-01-01T00:00:00Z", + "dropped_events_total": 1, + "dropped_through_position": 1, + "event_names": [ + "Example Name" + ], + "id": "string", + "last_overflow_at": "2024-01-01T00:00:00Z", + "leased_count": 1, + "max_pending_events": 1, + "name": "Example Name", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "queue_epoch": 1, + "retention_seconds": 1, + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "status": "active", + "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "updated_at": "2024-01-01T00:00:00Z", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "visibility_timeout_seconds": 1 + } + ], + "page": 1, + "per_page": 1, + "total_count": 1, + "total_pages": 1 + }, + "properties": { + "data": { + "items": { + "$ref": "#/components/schemas/EventSubscription" + }, + "type": "array" + }, + "page": { + "example": 1, + "type": "integer" + }, + "per_page": { + "example": 1, + "type": "integer" + }, + "total_count": { + "example": 1, + "type": "integer" + }, + "total_pages": { + "example": 1, + "type": "integer" + } + }, + "required": [ + "data", + "page", + "per_page", + "total_count", + "total_pages" + ], + "type": "object" + }, + "EventSubscriptionQueue": { + "description": "A cursor-paginated non-reserving view of a subscription queue.", + "example": { + "after_cursor": "string", + "before_cursor": "string", + "data": [ + { + "delivery_id": "string", + "event": { + "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "created_at": "2024-01-01T00:00:00Z", + "event_name": "Example Name", + "id": "string", + "idempotency_key": "string", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "payload": {}, + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" + }, + "lease_expires_at": "2024-01-01T00:00:00Z", + "receive_count": 1, + "sequence": 1, + "state": "available" + } + ], + "dropped_events_total": 1, + "dropped_through_position": 1, + "has_more": true, + "queue_epoch": 1 + }, + "properties": { + "after_cursor": { + "example": "string", + "type": "string" + }, + "before_cursor": { + "example": "string", + "type": "string" + }, + "data": { + "items": { + "$ref": "#/components/schemas/EventSubscriptionQueueEntry" + }, + "type": "array" + }, + "dropped_events_total": { + "example": 1, + "type": "integer" + }, + "dropped_through_position": { + "example": 1, + "type": "integer" + }, + "has_more": { + "example": true, + "type": "boolean" + }, + "queue_epoch": { + "example": 1, + "type": "integer" + } + }, + "required": [ + "data", + "has_more", + "queue_epoch", + "dropped_events_total", + "dropped_through_position" + ], + "type": "object" + }, + "EventSubscriptionQueueEntry": { + "description": "A non-reserving view of one queued delivery.", + "example": { + "delivery_id": "string", + "event": { + "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "created_at": "2024-01-01T00:00:00Z", + "event_name": "Example Name", + "id": "string", + "idempotency_key": "string", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "payload": {}, + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" + }, + "lease_expires_at": "2024-01-01T00:00:00Z", + "receive_count": 1, + "sequence": 1, + "state": "available" + }, + "properties": { + "delivery_id": { + "example": "string", + "type": "string" + }, + "event": { + "$ref": "#/components/schemas/DomainEvent" + }, + "lease_expires_at": { + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "type": "string" + }, + "receive_count": { + "example": 1, + "type": "integer" + }, + "sequence": { + "example": 1, + "type": "integer" + }, + "state": { + "enum": [ + "available", + "leased" + ], + "example": "available", + "type": "string" + } + }, + "required": [ + "delivery_id", + "sequence", + "state", + "receive_count", + "event" + ], + "type": "object" + }, + "Extraction": { + "description": "An extraction job: yields text from a document or website into a destination namespace, without committing knowledge to an agent.", + "example": { + "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "byte_count": 1, + "created_at": "2024-01-01T00:00:00Z", + "destination": {}, + "failure_reason": "fetch_failed", + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "id": "ext_0aBcDeFgHiJkLmNoPqRsTu", + "kind": "document", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "output_count": 1, + "outputs": [ + { + "created_at": "2024-01-01T00:00:00Z", + "file": { + "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "content_type": "application/json", + "created_at": "2024-01-01T00:00:00Z", + "filename": "document.pdf", + "id": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "image_source": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + }, + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "share_url": "https://example.com", + "size": 1024, + "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "updated_at": "2024-01-01T00:00:00Z", + "url": "https://example.com", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" + }, + "id": "exo_0aBcDeFgHiJkLmNoPqRsTu", + "ordinal": 1, + "source_url": "https://example.com", + "state": "done" + } + ], + "state": "pending", + "updated_at": "2024-01-01T00:00:00Z", + "url": "https://example.com" + }, + "properties": { + "agent": { + "description": "Owning agent (`agt_...`); `null` when not agent-scoped.", + "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "byte_count": { + "description": "Total bytes across produced storage files (a derived aggregate).", + "example": 1, + "type": "integer" + }, + "created_at": { + "description": "When the extraction was created (ISO 8601).", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "type": "string" + }, + "destination": { + "description": "Where outputs were written: `{ kind, path_prefix }`.", + "example": {}, + "type": "object" + }, + "failure_reason": { + "description": "Failure category when `state` is `failed`; `null` otherwise.", + "enum": [ + "fetch_failed", + "unsupported_content", + "extraction_failed", + "timeout", + "internal_error" + ], + "example": "fetch_failed", + "type": "string" + }, + "file": { + "description": "Source file (`fil_...`) for document extraction; `null` for link/site.", + "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "id": { + "description": "Extraction ID (`ext_...`).", + "example": "ext_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "kind": { + "description": "What is being extracted.", + "enum": [ + "document", + "link", + "site" + ], + "example": "document", + "type": "string" + }, + "org": { + "description": "Owning organization (`org_...`).", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "output_count": { + "description": "Number of produced output files (a derived aggregate).", + "example": 1, + "type": "integer" + }, + "outputs": { + "description": "Produced output files; populated only when the association is preloaded.", + "items": { + "$ref": "#/components/schemas/ExtractionOutput" + }, + "type": "array" + }, + "state": { + "description": "Lifecycle state of the extraction job.", + "enum": [ + "pending", + "running", + "done", + "failed" + ], + "example": "pending", + "type": "string" + }, + "updated_at": { + "description": "When the extraction was last updated (ISO 8601).", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "type": "string" + }, + "url": { + "description": "Source URL for link/site extraction; `null` for document.", + "example": "https://example.com", + "type": "string" + } + }, + "required": [ + "id" + ], + "type": "object" + }, + "ExtractionOutput": { + "description": "A produced file tracked by an extraction. Type, size, and URL live on the file it points at.", + "example": { + "created_at": "2024-01-01T00:00:00Z", + "file": { + "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "content_type": "application/json", + "created_at": "2024-01-01T00:00:00Z", + "filename": "document.pdf", + "id": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "image_source": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + }, + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "share_url": "https://example.com", + "size": 1024, + "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "updated_at": "2024-01-01T00:00:00Z", + "url": "https://example.com", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" + }, + "id": "exo_0aBcDeFgHiJkLmNoPqRsTu", + "ordinal": 1, + "source_url": "https://example.com", + "state": "done" + }, + "properties": { + "created_at": { + "description": "When this output was produced (ISO 8601).", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "type": "string" + }, + "file": { + "$ref": "#/components/schemas/StorageFile", + "description": "The produced file. For a config destination this is the `Storage.File` backing the versioned config row; type, size, and URL live here." + }, + "id": { + "description": "Output ID (`exo_...`).", + "example": "exo_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "ordinal": { + "description": "Position of this output within the extraction's output set.", + "example": 1, + "type": "integer" + }, + "source_url": { + "description": "The crawled page path or document path this output came from.", + "example": "https://example.com", + "type": "string" + }, + "state": { + "description": "Output state.", + "enum": [ + "done", + "failed" + ], + "example": "done", + "type": "string" + } + }, + "required": [ + "id" + ], + "type": "object" + }, + "HealthActionListResponse": { + "description": "List response containing agent health actions for a given agent or organization.", + "example": { + "data": [ + { + "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "created_at": "2024-01-01T00:00:00Z", + "depends_on": [ + "string" + ], + "description": "An example description.", + "id": "aha_0aBcDeFgHiJkLmNoPqRsTu", + "kind": "env_var", + "last_verified_at": "2024-01-01T00:00:00Z", + "last_verifier_message": "string", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "params": { + "key": "value" + }, + "required": true, + "sort_order": 1, + "source": "setup", + "status": "pending", + "title": "Example Title", + "updated_at": "2024-01-01T00:00:00Z", + "verify_config": {} + } + ] + }, + "properties": { + "data": { + "description": "Array of agent health action objects representing setup checklist items and probe-detected issues.", + "items": { + "$ref": "#/components/schemas/AgentHealthAction" + }, + "type": "array" + } + }, + "required": [ + "data" + ], + "type": "object" + }, + "ImageSource": { + "description": "Resolved metadata for an image, including its delivery URL, dimensions, and optional references to the underlying storage file or media record.", + "example": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + }, + "properties": { + "file": { + "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", + "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "height": { + "description": "Height of the image in pixels. `null` if not known.", + "example": 600, + "nullable": true, + "type": "integer" + }, + "media": { + "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", + "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "mime_type": { + "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", + "example": "application/json", + "nullable": true, + "type": "string" + }, + "refresh_url": { + "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.", + "example": "https://example.com", + "nullable": true, + "type": "string" + }, + "url": { + "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.", + "example": "https://example.com", + "nullable": true, + "type": "string" + }, + "width": { + "description": "Width of the image in pixels. `null` if not known.", + "example": 800, + "nullable": true, + "type": "integer" + } + }, + "type": "object" + }, + "Installation": { + "description": "An installation representing a connection between an agent and an external service or enablement channel. Tracks configuration, lifecycle state, and any bound integration.", + "example": { + "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "config": {}, + "created_at": "2024-01-01T00:00:00Z", + "id": "cin_0aBcDeFgHiJkLmNoPqRsTu", + "kind": "enablement/github_app", + "lookup_key": "string", + "shared_integration": "int_0aBcDeFgHiJkLmNoPqRsTu", + "state": "active", + "status_payload": {}, + "updated_at": "2024-01-01T00:00:00Z" + }, + "properties": { + "agent": { + "description": "ID of the agent that owns this installation (`agi_...`). `null` if the installation has no agent owner.", + "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" }, "config": { "description": "Kind-specific configuration object for this installation. Shape depends on the `kind` value. `null` if the kind requires no configuration.", @@ -12409,6 +13464,7 @@ "lookup_key": { "description": "Stored `lookup_key` for this config after any suffix has been applied. `null` for `File` children inside a skill bundle, which are keyed by `(parent_id, relative_path)` rather than by `lookup_key`.", "example": "my-skill", + "nullable": true, "type": "string" } }, @@ -12832,6 +13888,7 @@ "content_type": { "description": "MIME type of this variant's file (e.g., `\"image/jpeg\"`, `\"video/mp4\"`). `null` if the file is not loaded.", "example": "application/json", + "nullable": true, "type": "string" }, "created_at": { @@ -12848,11 +13905,13 @@ "filename": { "description": "Original filename of the uploaded file for this variant. `null` if the file is not loaded.", "example": "string", + "nullable": true, "type": "string" }, "height": { "description": "Height of this variant in pixels. `null` if not recorded.", "example": 600, + "nullable": true, "type": "integer" }, "id": { @@ -12861,8 +13920,22 @@ "type": "string" }, "image_source": { - "$ref": "#/components/schemas/ImageSource", - "description": "Resolved image delivery metadata for this variant, including dimensions and CDN URL. `null` for non-image content types." + "allOf": [ + { + "$ref": "#/components/schemas/ImageSource" + } + ], + "description": "Resolved image delivery metadata for this variant, including dimensions and CDN URL. `null` for non-image content types.", + "example": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + }, + "nullable": true }, "updated_at": { "description": "When this variant was last updated (ISO 8601).", @@ -12873,6 +13946,7 @@ "url": { "description": "Signed download URL for this variant, resolved at request time. `null` if the file is unavailable.", "example": "https://example.com", + "nullable": true, "type": "string" }, "variant_key": { @@ -12883,6 +13957,7 @@ "width": { "description": "Width of this variant in pixels. `null` if not recorded.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -12994,7 +14069,7 @@ ], "branched_thread": "string", "content": "Hello, how can I help you today?", - "created_at": "2024-01-01T00:00:00Z", + "created_at": "string", "has_replies": true, "id": "msg_0aBcDeFgHiJkLmNoPqRsTu", "idempotency_key": "01234567-89ab-cdef-0123-456789abcdef", @@ -13153,7 +14228,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "root_message_id": "string", @@ -13161,13 +14236,46 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "properties": { "acl": { - "$ref": "#/components/schemas/Acl", - "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." + "allOf": [ + { + "$ref": "#/components/schemas/Acl" + } + ], + "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.", + "example": { + "add": [ + { + "actions": [ + "read", + "write" + ], + "principal": "string", + "principal_type": "user" + } + ], + "grants": [ + { + "actions": [ + "read", + "write" + ], + "principal": "string", + "principal_type": "user" + } + ], + "remove": [ + { + "principal": "string", + "principal_type": "user" + } + ] + }, + "nullable": true }, "actors": { "description": "Resolved actor descriptors for the message sender, combining identity and display metadata. Always contains exactly one entry.", @@ -13179,6 +14287,7 @@ "agent": { "description": "ID of the agent user that sent this message (`agi_...`). `null` for messages sent by human users.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "agent_mode": { @@ -13188,6 +14297,7 @@ "embedded" ], "example": "cli", + "nullable": true, "type": "string" }, "attachments": { @@ -13200,17 +14310,18 @@ "branched_thread": { "description": "ID of the thread that was branched from this message (`thr_...`). `null` if this message has not spawned a branch thread.", "example": "string", + "nullable": true, "type": "string" }, "content": { "description": "Text content of the message. `null` for messages that contain only attachments.", "example": "Hello, how can I help you today?", + "nullable": true, "type": "string" }, "created_at": { "description": "When the message was posted (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "has_replies": { @@ -13226,6 +14337,7 @@ "idempotency_key": { "description": "Client-supplied idempotency key used to deduplicate message sends. `null` if the sender did not provide one.", "example": "01234567-89ab-cdef-0123-456789abcdef", + "nullable": true, "type": "string" }, "is_deleted": { @@ -13236,6 +14348,7 @@ "legacy_agent": { "description": "Identifier of the legacy chat agent that sent this message, if applicable. `null` for messages sent by users or modern agent users.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -13248,6 +14361,7 @@ "org": { "description": "ID of the organization that owns this message (`org_...`).", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "reactions": { @@ -13260,6 +14374,7 @@ "rendering_mode": { "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.", "example": "reply", + "nullable": true, "type": "string" }, "replies": { @@ -13275,11 +14390,13 @@ "replies_after_cursor": { "description": "Opaque pagination cursor to fetch replies posted after the current page. Only present when inline replies are included in the response.", "example": "string", + "nullable": true, "type": "string" }, "replies_before_cursor": { "description": "Opaque pagination cursor to fetch replies posted before the current page. Only present when inline replies are included in the response.", "example": "string", + "nullable": true, "type": "string" }, "reply_count": { @@ -13422,9 +14539,10 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, + "nullable": true, "type": "object" }, "root_message_id": { @@ -13436,27 +14554,180 @@ "sandbox": { "description": "ID of the developer sandbox this message belongs to (`dsb_...`). `null` for non-sandbox messages.", "example": "string", + "nullable": true, "type": "string" }, "team": { "description": "ID of the team this message is scoped to (`tem_...`). `null` if the message is not team-scoped.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "thread": { - "description": "ID of the thread this message belongs to (`thr_...`). `null` for messages not yet associated with a thread.", + "description": "ID of the thread this message belongs to (`thr_...`).", "example": "string", "type": "string" }, "type": { "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.", "example": "note", + "nullable": true, "type": "string" }, "user": { "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.", - "example": "string", - "type": "string" + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "oneOf": [ + { + "type": "string" + }, + { + "description": "A platform user account. Represents a human or system actor that can own threads, belong to an organization, and interact with the API.", + "example": { + "alias": "jdoe", + "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "email": "user@example.com", + "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "is_system_user": true, + "metadata": { + "key": "value" + }, + "name": "Example Name", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "org_name": "Example Name", + "org_role": "member", + "org_slug": "example-slug", + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "sandbox_name": "Example Name" + }, + "properties": { + "alias": { + "description": "Short handle or alias for the user. `null` if not set.", + "example": "jdoe", + "nullable": true, + "type": "string" + }, + "app": { + "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.", + "example": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "app_name": { + "description": "Display name of the user's app. `null` when the app association was not preloaded by the caller.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "created_by_agent_user": { + "description": "Agent user that created this account (`usr_...`). `null` unless an agent created it.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_developer": { + "description": "Developer account that created this user (`dva_...`). `null` unless created via a developer token.", + "example": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_org": { + "description": "Org of the principal that created this user (`org_...`). `null` on legacy rows.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_team": { + "description": "Team that created this user (`tem_...`). `null` unless created as a team.", + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_user": { + "description": "User who created this account (`usr_...`). `null` on self-signup or legacy rows.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "email": { + "description": "Email address of the user.", + "example": "user@example.com", + "nullable": true, + "type": "string" + }, + "id": { + "description": "User ID (`usr_...`).", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "is_system_user": { + "description": "`true` if this account is an internal system user rather than a human. System users are created automatically by the platform.", + "example": true, + "type": "boolean" + }, + "metadata": { + "description": "Arbitrary key-value metadata attached to the user. Defaults to an empty object.", + "example": { + "key": "value" + }, + "type": "object" + }, + "name": { + "description": "Full display name of the user. `null` if the user has not set a name.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "org": { + "description": "ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "org_name": { + "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.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "org_role": { + "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.", + "example": "member", + "nullable": true, + "type": "string" + }, + "org_slug": { + "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.", + "example": "example-slug", + "nullable": true, + "type": "string" + }, + "sandbox": { + "description": "ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.", + "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "sandbox_name": { + "description": "Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.", + "example": "Example Name", + "nullable": true, + "type": "string" + } + }, + "required": [ + "id" + ], + "type": "object" + } + ] }, "visibility": { "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.", @@ -13694,6 +14965,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -13704,6 +14980,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -13889,7 +15166,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" } ], @@ -14202,6 +15479,83 @@ ], "type": "object" }, + "ProductKnowledgeReconcileFailure": { + "description": "One stamped customer whose product-knowledge tool update did not converge.", + "example": { + "customer_key": "string", + "error": "string", + "retryable": true + }, + "properties": { + "customer_key": { + "description": "Stable vendor-defined key for the customer whose agent did not converge.", + "example": "string", + "type": "string" + }, + "error": { + "description": "Stable failure reason for operator and vendor feedback.", + "example": "string", + "type": "string" + }, + "retryable": { + "description": "Whether rerunning the desired-state reconciliation is safe.", + "example": true, + "type": "boolean" + } + }, + "required": [ + "customer_key", + "retryable", + "error" + ], + "type": "object" + }, + "ProductKnowledgeReconcileResponse": { + "description": "Desired-state reconciliation result for a CM install's stamped agents.", + "example": { + "complete": true, + "failures": [ + { + "customer_key": "string", + "error": "string", + "retryable": true + } + ], + "reconciled_customers": [ + "string" + ] + }, + "properties": { + "complete": { + "description": "True when every stamped customer agent now has the desired source allowlist.", + "example": true, + "type": "boolean" + }, + "failures": { + "description": "Per-customer failures. Empty when reconciliation is complete.", + "items": { + "$ref": "#/components/schemas/ProductKnowledgeReconcileFailure" + }, + "type": "array" + }, + "reconciled_customers": { + "description": "Customer keys whose agent tool config is converged.", + "example": [ + "string" + ], + "items": { + "type": "string" + }, + "type": "array" + } + }, + "required": [ + "complete", + "reconciled_customers", + "failures" + ], + "type": "object" + }, "RoutinePreset": { "description": "A named preset that defines the execution model and constraints for a routine. Presets are shared definitions; individual routines reference a preset by name.", "example": { @@ -14376,6 +15730,7 @@ "description": "When an eval sandbox expires and becomes eligible for platform cleanup. `null` for ordinary developer sandboxes.", "example": "2024-01-01T00:00:00Z", "format": "date-time", + "nullable": true, "type": "string" }, "id": { @@ -14398,20 +15753,37 @@ "org": { "description": "Organization ID this sandbox is scoped to, or `null` for an app-level sandbox.", "example": "string", + "nullable": true, "type": "string" }, "org_logo": { - "$ref": "#/components/schemas/ImageSource", - "description": "Logo of the owning organization, when present." + "allOf": [ + { + "$ref": "#/components/schemas/ImageSource" + } + ], + "description": "Logo of the owning organization, when present.", + "example": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + }, + "nullable": true }, "org_name": { "description": "Display name of the owning organization, when org-scoped.", "example": "Example Name", + "nullable": true, "type": "string" }, "purpose": { "description": "Sandbox purpose marker. `\"eval\"` marks a remote-eval sandbox; `null` for ordinary developer sandboxes.", "example": "string", + "nullable": true, "type": "string" }, "slug": { @@ -14457,6 +15829,7 @@ "description": "When this key expires and becomes invalid. `null` if the key does not expire.", "example": "2024-01-01T00:00:00Z", "format": "date-time", + "nullable": true, "type": "string" }, "full_key": { @@ -14472,17 +15845,20 @@ "key_hint": { "description": "A short hint showing the last four characters of the key, used for identification. `null` if no hint is available.", "example": "Xk9q", + "nullable": true, "type": "string" }, "key_value": { "description": "The full key value for `\"publishable\"` keys. `null` for `\"secret\"` keys; use `full_key` instead, which is returned only at creation time.", "example": "string", + "nullable": true, "type": "string" }, "last_used_at": { "description": "When this key was last used to authenticate a request. `null` if the key has never been used.", "example": "2024-01-01T00:00:00Z", "format": "date-time", + "nullable": true, "type": "string" }, "status": { @@ -14518,6 +15894,9 @@ "integration": "int_0aBcDeFgHiJkLmNoPqRsTu", "is_ext_shared_cached": true, "is_private_cached": true, + "mirrors": [ + "string" + ], "muted": true, "muted_until": "string", "reply_style": "string", @@ -14588,6 +15967,16 @@ "example": true, "type": "boolean" }, + "mirrors": { + "description": "IDs of every mirror thread this channel's messages land in (`thr_…` public IDs) that the caller can read, including any legacy peel or chain threads. Empty for a caller with no membership on any of them, and for a channel that has not mirrored anything yet. IDs only: reading a mirror's contents still requires membership on it.", + "example": [ + "string" + ], + "items": { + "type": "string" + }, + "type": "array" + }, "muted": { "description": "Whether the resident agent is currently muted. A muted resident keeps mirroring the channel (reading) but stops replying. A timed mute expires automatically at `muted_until`; this reflects the effective state as of now. Defaults to `false`.", "example": true, @@ -14604,15 +15993,16 @@ "type": "string" }, "resident_agent": { - "description": "ID of the non-concierge agent selected by Slack ingress. `null` when ingress falls back to the concierge.", + "description": "ID of the resident agent selected by Slack ingress. `null` when no resident is attached and the channel is an observer.", "example": "string", "type": "string" }, "route_kind": { - "description": "Effective Slack ingress route: `fda` for a team-bound resident, `resident` for an unbound resident, or `concierge` when no non-concierge agent is attached.", + "description": "Effective Slack ingress route. `fda` — a resident on a team-bound channel, replying through the Forward Deployed Agent chain. `resident` — a resident on an internal channel, replying through the channel mirror. `observer` — no resident is attached, so the channel is recorded and nobody replies. `concierge` — no longer returned anywhere; until Track F it was the value for a channel with no resident, meaning the shared concierge agent answered there. The value is retained in this enum so consumers matching on it do not break, and its removal rides a deliberate API change.", "enum": [ "fda", "resident", + "observer", "concierge" ], "example": "fda", @@ -14666,6 +16056,9 @@ "integration": "int_0aBcDeFgHiJkLmNoPqRsTu", "is_ext_shared_cached": true, "is_private_cached": true, + "mirrors": [ + "string" + ], "muted": true, "muted_until": "string", "reply_style": "string", @@ -14719,6 +16112,167 @@ ], "type": "object" }, + "SlackDeliveryOutcome": { + "description": "What happened to one agent message this platform sent to a Slack channel. Lets you confirm delivery, or find out why a reply never arrived, without reading the channel's mirrored conversation.", + "example": { + "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "binding": "scb_0aBcDeFgHiJkLmNoPqRsTu", + "channel": "C01234ABCDE", + "failure_reason": "slack:channel_not_found", + "guard_kind": "RegexMatch", + "guard_labels": [ + "string" + ], + "id": "sdo_0aBcDeFgHiJkLmNoPqRsTu", + "message": "msg_0aBcDeFgHiJkLmNoPqRsTu", + "operation": "post", + "outcome": "delivered", + "recorded_at": "2024-01-01T00:00:00Z", + "thread_ts": "string" + }, + "properties": { + "agent": { + "description": "ID of the agent whose message this was.", + "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "binding": { + "description": "ID of the Slack channel binding in force for this send. `null` when no binding could be resolved, in which case the send was treated as cross-org and floored on that basis.", + "example": "scb_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "channel": { + "description": "Slack channel ID the send was addressed to.", + "example": "C01234ABCDE", + "type": "string" + }, + "failure_reason": { + "description": "For a `failed` send, a short machine-readable cause — `slack:` when Slack rejected the call, or `floor_config` when the content floor could not be evaluated and the send failed closed.", + "example": "slack:channel_not_found", + "type": "string" + }, + "guard_kind": { + "description": "For a withheld send, the kind of guard that stopped it — `RegexMatch`, `ContainsAny`, `ContainsString`, or `LLMJudge`. `null` when the send was not withheld by a guard.", + "example": "RegexMatch", + "type": "string" + }, + "guard_labels": { + "description": "For a withheld send, the labels of the guards that stopped it (for example `Contains AWS access key ID`). These are the content policy's own descriptions, recorded as they read at the time of the send; they never contain the withheld message.", + "example": [ + "string" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "id": { + "description": "Unique identifier for this delivery outcome.", + "example": "sdo_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "message": { + "description": "ID of the platform message this attempt was carrying. Reading that message still requires access to its thread — this field correlates, it does not grant.", + "example": "msg_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "operation": { + "description": "Which Slack call the attempt made. `post` — a new message in the channel, visible to everyone in it. `post_ephemeral` — a message only one named channel member could see; Slack returns no durable timestamp for one, so it has no `thread_ts` to correlate and cannot be found in the channel's history afterwards. `update` — replacing an existing message (typically a thinking placeholder).", + "enum": [ + "post", + "post_ephemeral", + "update" + ], + "example": "post", + "type": "string" + }, + "outcome": { + "description": "What happened to the send. `delivered` — Slack accepted the message. `floored` — a deterministic content guard withheld it, so it never left. `judge_refused` — the cross-org judge decided it was not appropriate for this channel's audience. `failed` — Slack rejected the call, or the content floor could not be evaluated and the send failed closed.", + "enum": [ + "delivered", + "floored", + "judge_refused", + "failed" + ], + "example": "delivered", + "type": "string" + }, + "recorded_at": { + "description": "When the send was attempted.", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "type": "string" + }, + "thread_ts": { + "description": "Slack thread timestamp the send targeted, letting attempts be grouped into the conversation they belong to. `null` for a top-level channel post.", + "example": "string", + "type": "string" + } + }, + "required": [ + "id", + "outcome", + "operation", + "channel", + "recorded_at" + ], + "type": "object" + }, + "SlackDeliveryOutcomeListResponse": { + "description": "A page of delivery outcomes for one Slack channel, newest first. Page through history with the returned cursors; `since` and `outcome` are filters, not paging controls.", + "example": { + "after_cursor": "string", + "before_cursor": "string", + "data": [ + { + "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "binding": "scb_0aBcDeFgHiJkLmNoPqRsTu", + "channel": "C01234ABCDE", + "failure_reason": "slack:channel_not_found", + "guard_kind": "RegexMatch", + "guard_labels": [ + "string" + ], + "id": "sdo_0aBcDeFgHiJkLmNoPqRsTu", + "message": "msg_0aBcDeFgHiJkLmNoPqRsTu", + "operation": "post", + "outcome": "delivered", + "recorded_at": "2024-01-01T00:00:00Z", + "thread_ts": "string" + } + ], + "has_more": true + }, + "properties": { + "after_cursor": { + "description": "Opaque cursor for the page of newer outcomes. Pass back as `after_cursor` to poll for attempts recorded since. `null` when the page is empty.", + "example": "string", + "type": "string" + }, + "before_cursor": { + "description": "Opaque cursor for the page of older outcomes. Pass back as `before_cursor` to continue into history. `null` when the page is empty.", + "example": "string", + "type": "string" + }, + "data": { + "description": "Delivery outcomes matching the query, newest attempt first.", + "items": { + "$ref": "#/components/schemas/SlackDeliveryOutcome" + }, + "type": "array" + }, + "has_more": { + "description": "True when more outcomes exist beyond this page.", + "example": true, + "type": "boolean" + } + }, + "required": [ + "data", + "has_more" + ], + "type": "object" + }, "SolutionAutomationInvokeContract": { "description": "The schema-driven values an installer may lock when provisioning an invoked automation template.", "example": { @@ -14740,13 +16294,28 @@ "input_schema": { "description": "JSON Schema validated against the whole invoke payload, from the automation's `input_schema_config`. `null` when none is configured.", "example": {}, + "nullable": true, "type": "object" }, "participants": { "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.", + "example": [ + { + "description": "An example description.", + "name": "reporter", + "required": true, + "type": "agent_user" + } + ], "items": { - "$ref": "#/components/schemas/AutomationParticipantSlot" + "allOf": [ + { + "$ref": "#/components/schemas/AutomationParticipantSlot" + } + ], + "nullable": true }, + "nullable": true, "type": "array" }, "prefills": { @@ -14782,13 +16351,34 @@ }, "properties": { "automation_type": { - "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`).", + "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", "example": "string", + "nullable": true, "type": "string" }, "invoke_contract": { - "$ref": "#/components/schemas/SolutionAutomationInvokeContract", - "description": "Schema-driven payload and participant inputs for an invoked automation. Used by installation clients to collect locked prefills before provisioning." + "allOf": [ + { + "$ref": "#/components/schemas/SolutionAutomationInvokeContract" + } + ], + "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.", + "example": { + "input_schema": {}, + "participants": [ + { + "description": "An example description.", + "name": "reporter", + "required": true, + "type": "agent_user" + } + ], + "prefills": { + "participants": {}, + "payload": {} + } + }, + "nullable": true }, "type": { "default": "automation", @@ -15242,7 +16832,7 @@ "SolutionImportResponse": { "description": "The result of importing a Solution bundle into the library, including the Solution config record, a structured import result, and the list of all configs persisted during the transaction.", "example": { - "created_at": "2024-01-01T00:00:00Z", + "created_at": "string", "id": "id_0aBcDeFgHiJkLmNoPqRsTu", "import_result": { "code": "string", @@ -15328,14 +16918,13 @@ "upgrade_available": true, "virtual_path": "string" }, - "updated_at": "2024-01-01T00:00:00Z", + "updated_at": "string", "virtual_path": "string" }, "properties": { "created_at": { "description": "When the Solution config record was first created (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "id": { @@ -15362,6 +16951,7 @@ "lookup_key": { "description": "The `lookup_key` stored on the Solution config after the import's suffix normalization. `null` when the Solution was not given a lookup key.", "example": "string", + "nullable": true, "type": "string" }, "solution": { @@ -15370,13 +16960,13 @@ }, "updated_at": { "description": "When the Solution config record was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "virtual_path": { "description": "The `virtual_path` stored on the Solution config, used as the stable dedupe key across owner scopes. `null` when no virtual path was assigned.", "example": "string", + "nullable": true, "type": "string" } }, @@ -15410,6 +17000,7 @@ "code": { "description": "Machine-readable conflict code present when `status` is `\"conflict\"`, identifying the specific conflict reason. `null` when `status` is `\"ready\"`.", "example": "string", + "nullable": true, "type": "string" }, "dry_run": { @@ -15420,16 +17011,19 @@ "existing_solution_version": { "description": "Semver string of the Solution version already present in the library. `null` when no prior version exists.", "example": "1.0.0", + "nullable": true, "type": "string" }, "incoming_solution_version": { "description": "Semver string of the Solution version in the bundle being imported. `null` when the bundle does not declare a version.", "example": "1.0.0", + "nullable": true, "type": "string" }, "message": { "description": "Human-readable description of the import status or conflict reason, suitable for display in a confirmation dialog. `null` when no detail is available.", "example": "string", + "nullable": true, "type": "string" }, "status": { @@ -15514,6 +17108,7 @@ "lookup_key": { "description": "The `lookup_key` stamped on the provisioned resource. `null` for `AgentSkill`, which is a join record and does not carry a lookup key.", "example": "string", + "nullable": true, "type": "string" }, "solution": { @@ -15576,16 +17171,19 @@ "agent": { "description": "Materialized agent for this customer (`agi_...`). `null` for a row without an agent.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "agent_name": { "description": "Human-readable display name of the materialized agent. `null` when no agent is visible.", "example": "Example Name", + "nullable": true, "type": "string" }, "attachment_ref": { "description": "Opaque tagged reference to the deployment target. Consumers interpret its kind.", "example": {}, + "nullable": true, "type": "object" }, "created_at": { @@ -15602,6 +17200,7 @@ "customer_label": { "description": "Human-readable customer label. `null` when the vendor did not provide one.", "example": "string", + "nullable": true, "type": "string" }, "id": { @@ -15612,16 +17211,19 @@ "local_edit_count": { "description": "Count of local agent edits relative to the pinned template. `null` when unavailable.", "example": 1, + "nullable": true, "type": "integer" }, "pinned_template_version": { "description": "Pinned template version record (`cfv_...`). `null` when no version is pinned.", "example": "cfv_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "pinned_version_number": { "description": "Human-readable version number of the pinned template. `null` when unavailable.", "example": 1, + "nullable": true, "type": "integer" }, "solution_template_config": { @@ -15835,7 +17437,7 @@ "category_keys": [ "string" ], - "created_at": "2024-01-01T00:00:00Z", + "created_at": "string", "description": "An example description.", "events": {}, "id": "id_0aBcDeFgHiJkLmNoPqRsTu", @@ -15885,7 +17487,7 @@ "virtual_path": "string" } ], - "updated_at": "2024-01-01T00:00:00Z", + "updated_at": "string", "upgrade_available": true, "virtual_path": "string" }, @@ -15902,13 +17504,13 @@ }, "created_at": { "description": "When the Solution config was first imported (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "events": { @@ -15924,6 +17526,7 @@ "image_url": { "description": "Absolute URL of the Solution's cover image — the bundled asset the body's `image:` field names. A stable, non-expiring capability URL (like `org_logo.url`), safe to hold in caches and OpenGraph tags; it 404s if the Solution stops declaring a cover. `null` when the Solution has no cover image, and always `null` for org-scoped rows — the permanent URL is minted for system-scope (catalog) Solutions only.", "example": "https://example.com", + "nullable": true, "type": "string" }, "kind": { @@ -15934,16 +17537,19 @@ "latest_solution": { "description": "When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "latest_version": { "description": "When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", "example": "1.0.0", + "nullable": true, "type": "string" }, "lookup_key": { "description": "The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -15956,25 +17562,43 @@ "name": { "description": "Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "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.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_logo": { - "$ref": "#/components/schemas/ImageSource", - "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." + "allOf": [ + { + "$ref": "#/components/schemas/ImageSource" + } + ], + "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.", + "example": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + }, + "nullable": true }, "org_name": { "description": "Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_slug": { "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.", "example": "example-slug", + "nullable": true, "type": "string" }, "owners": { @@ -15990,6 +17614,7 @@ "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "screenshot_urls": { @@ -16005,11 +17630,13 @@ "solution_id": { "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.", "example": "01234567-89ab-cdef-0123-456789abcdef", + "nullable": true, "type": "string" }, "solution_version": { "description": "Semver string declared in the Solution body (e.g. `\"1.2.0\"`). `null` when the body does not declare a version.", "example": "1.2.0", + "nullable": true, "type": "string" }, "tag_keys": { @@ -16025,6 +17652,7 @@ "template_kind": { "description": "Wrapped template kind — `\"AgentTemplate\"`, `\"AutomationTemplate\"`, `\"AgentRoutineTemplate\"`, `\"AgentToolTemplate\"`, `\"AgentComputerTemplate\"`, or `\"SolutionTemplateRef\"` for ref-mode bundles.", "example": "AgentTemplate", + "nullable": true, "type": "string" }, "templates": { @@ -16036,8 +17664,7 @@ }, "updated_at": { "description": "When the Solution config was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "upgrade_available": { @@ -16048,6 +17675,7 @@ "virtual_path": { "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.", "example": "string", + "nullable": true, "type": "string" } }, @@ -16276,20 +17904,28 @@ "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "details": { - "$ref": "#/components/schemas/SolutionTemplateDetails", - "description": "Template-kind-specific details selected by the `type` discriminator. `null` when this template kind has no additional details." + "allOf": [ + { + "$ref": "#/components/schemas/SolutionTemplateDetails" + } + ], + "description": "Template-kind-specific details selected by the `type` discriminator. `null` when this template kind has no additional details.", + "nullable": true }, "display_name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "id": { "description": "Template config ID (`cfg_...`). `null` for inline-only templates.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "kind": { @@ -16300,21 +17936,25 @@ "lookup_key": { "description": "Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", "example": "string", + "nullable": true, "type": "string" }, "name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "virtual_path": { "description": "Stable virtual path assigned to the template config. `null` when no virtual path was set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -16613,6 +18253,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -16623,6 +18268,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -16643,8 +18289,36 @@ "type": "object" }, "user": { - "$ref": "#/components/schemas/User", - "description": "The authenticated user associated with the token. `null` when the token is invalid or absent." + "allOf": [ + { + "$ref": "#/components/schemas/User" + } + ], + "description": "The authenticated user associated with the token. `null` when the token is invalid or absent.", + "example": { + "alias": "jdoe", + "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "email": "user@example.com", + "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "is_system_user": true, + "metadata": { + "key": "value" + }, + "name": "Example Name", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "org_name": "Example Name", + "org_role": "member", + "org_slug": "example-slug", + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "sandbox_name": "Example Name" + }, + "nullable": true } }, "required": [ @@ -16757,6 +18431,109 @@ ], "type": "object" }, + "SystemAccessToken": { + "description": "A long-lived API credential associated with a system account, used to authenticate server-to-server requests.", + "example": { + "created_at": "2024-01-01T00:00:00Z", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "expires_at": "2024-01-01T00:00:00Z", + "id": "sat_0aBcDeFgHiJkLmNoPqRsTu", + "last_used_at": "2024-01-01T00:00:00Z", + "name": "Example Name", + "revoked_at": "2024-01-01T00:00:00Z", + "scopes": "string", + "token": "string" + }, + "properties": { + "created_at": { + "description": "When this token was created (ISO 8601).", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "type": "string" + }, + "created_by_agent_user": { + "description": "Agent user that minted this token (`usr_...`). `null` unless an agent minted it.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_developer": { + "description": "Developer account that minted this token (`dva_...`). `null` unless minted with a developer token.", + "example": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_org": { + "description": "Org of the principal that minted this token (`org_...`). `null` on legacy rows.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_team": { + "description": "Team that minted this token (`tem_...`). `null` unless minted as a team.", + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_user": { + "description": "User who minted this token (`usr_...`). Distinct from the token subject. `null` on legacy rows.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "expires_at": { + "description": "When the token expires. `null` on legacy rows that predate stored expiry.", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "nullable": true, + "type": "string" + }, + "id": { + "description": "Token ID (`sat_...`).", + "example": "sat_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "last_used_at": { + "description": "When this token was last used to authenticate a request. `null` if the token has never been used.", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "nullable": true, + "type": "string" + }, + "name": { + "description": "Human-readable label assigned to this token at creation time. `null` when no label was supplied.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "revoked_at": { + "description": "When this token was revoked. `null` if the token is still active.", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "nullable": true, + "type": "string" + }, + "scopes": { + "description": "Space-separated OAuth scopes stamped on the token. `null` on legacy rows; treat as `full_access`.", + "example": "string", + "nullable": true, + "type": "string" + }, + "token": { + "description": "Raw bearer token string. Present only in the response to the create request; never returned again after that.", + "example": "string", + "type": "string" + } + }, + "required": [ + "id" + ], + "type": "object" + }, "Task": { "description": "A task representing a unit of work, optionally assignable to a user or agent.", "example": { @@ -16788,6 +18565,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -16817,6 +18595,9 @@ "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "priority": 2, "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", "status": "open", "subtasks_count": 1, "tags": [ @@ -16831,6 +18612,7 @@ "agent": { "description": "ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "blocked_by_count": { @@ -16842,6 +18624,7 @@ "description": "When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", "example": "2024-01-01T00:00:00Z", "format": "date-time", + "nullable": true, "type": "string" }, "comments_count": { @@ -16856,17 +18639,38 @@ "type": "string" }, "created_by_actor": { - "$ref": "#/components/schemas/Actor", - "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)." + "allOf": [ + { + "$ref": "#/components/schemas/Actor" + } + ], + "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).", + "example": { + "alias": "alice", + "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "name": "Example Name", + "profile_picture": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + } + }, + "nullable": true }, "created_by_agent": { "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.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "created_by_user": { "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.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "current_lease": { @@ -16886,12 +18690,20 @@ "description": { "description": "Long-form description or notes for the task. `null` if no description has been provided.", "example": "An example description.", + "nullable": true, "type": "string" }, "due_date": { "description": "Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", "example": "2024-01-01T00:00:00Z", "format": "date-time", + "nullable": true, + "type": "string" + }, + "epic": { + "description": "Free-form grouping label. `null` when the task is not in an epic.", + "example": "string", + "nullable": true, "type": "string" }, "id": { @@ -16926,25 +18738,48 @@ "org": { "description": "ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "owner_actor": { - "$ref": "#/components/schemas/Actor", - "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)." + "allOf": [ + { + "$ref": "#/components/schemas/Actor" + } + ], + "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).", + "example": { + "alias": "alice", + "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "name": "Example Name", + "profile_picture": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + } + }, + "nullable": true }, "owner_agent": { "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.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "owner_user": { "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.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "parent": { "description": "ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks. Subtasks nest exactly one level.", "example": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "priority": { @@ -16955,6 +18790,25 @@ "sandbox": { "description": "ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "source_id": { + "description": "Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", + "example": "string", + "nullable": true, + "type": "string" + }, + "source_scope": { + "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`.", + "example": "string", + "nullable": true, + "type": "string" + }, + "source_type": { + "description": "Kind of source object (for example `repository`). `null` when the task has no source.", + "example": "string", + "nullable": true, "type": "string" }, "status": { @@ -16980,11 +18834,13 @@ "team": { "description": "ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "thread": { "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.", "example": "thr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "updated_at": { @@ -16996,6 +18852,7 @@ "user": { "description": "ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" } }, @@ -17232,8 +19089,41 @@ }, "properties": { "acl": { - "$ref": "#/components/schemas/Acl", - "description": "Access control list governing visibility and join permissions for this team. `null` when no ACL restrictions are applied and the team inherits default access rules." + "allOf": [ + { + "$ref": "#/components/schemas/Acl" + } + ], + "description": "Access control list governing visibility and join permissions for this team. `null` when no ACL restrictions are applied and the team inherits default access rules.", + "example": { + "add": [ + { + "actions": [ + "read", + "write" + ], + "principal": "string", + "principal_type": "user" + } + ], + "grants": [ + { + "actions": [ + "read", + "write" + ], + "principal": "string", + "principal_type": "user" + } + ], + "remove": [ + { + "principal": "string", + "principal_type": "user" + } + ] + }, + "nullable": true }, "app": { "description": "ID of the developer application this team belongs to (`dap_...`). `null` if the team is not scoped to an app.", @@ -17243,6 +19133,7 @@ "badges": { "description": "Aggregated badge counts for the team, keyed by category. `null` when badge data is not loaded.", "example": {}, + "nullable": true, "type": "object" }, "created_at": { @@ -17254,6 +19145,7 @@ "description": { "description": "Human-readable description of the team's purpose. `null` if not set.", "example": "An example description.", + "nullable": true, "type": "string" }, "id": { @@ -17264,6 +19156,7 @@ "membership_status": { "description": "The authenticated viewer's role on this team. One of `\"owner\"`, `\"admin\"`, or `\"member\"`. `null` if the viewer is not a member.", "example": "member", + "nullable": true, "type": "string" }, "metadata": { @@ -17281,16 +19174,19 @@ "org": { "description": "ID of the organization this team belongs to (`org_...`). `null` if the team is not org-scoped.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the developer sandbox this team is scoped to (`dsb_...`). `null` outside sandbox contexts.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "slug": { "description": "URL-safe slug for the team, derived from the team name. `null` if not set.", "example": "example-slug", + "nullable": true, "type": "string" }, "updated_at": { @@ -17530,6 +19426,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -17540,14 +19441,201 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } }, "properties": { "agent": { - "$ref": "#/components/schemas/Agent", - "description": "The agent associated with this membership, as an expanded agent object. `null` when the member is a user, the type is unknown, or the association is not preloaded." + "allOf": [ + { + "$ref": "#/components/schemas/Agent" + } + ], + "description": "The agent associated with this membership, as an expanded agent object. `null` when the member is a user, the type is unknown, or the association is not preloaded.", + "example": { + "acl": { + "add": [ + { + "actions": [ + "read", + "write" + ], + "principal": "string", + "principal_type": "user" + } + ], + "grants": [ + { + "actions": [ + "read", + "write" + ], + "principal": "string", + "principal_type": "user" + } + ], + "remove": [ + { + "principal": "string", + "principal_type": "user" + } + ] + }, + "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "created_at": "2024-01-01T00:00:00Z", + "default_model": "claude-3-7-sonnet-latest", + "description": "An example description.", + "email": "user@example.com", + "id": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "identity": "You are a helpful assistant that answers questions about ArchAstro products.", + "last_applied_template_config": "cfg_0aBcDeFgHiJkLmNoPqRsTu", + "lookup_key": "string", + "metadata": { + "key": "value" + }, + "name": "Example Name", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "org_name": "Example Name", + "originator": "deploy-pipeline", + "phone_number": "+15555550123", + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_solution": { + "current_solution": { + "category_keys": [ + "string" + ], + "created_at": "2024-01-01T00:00:00Z", + "description": "An example description.", + "events": {}, + "id": "id_0aBcDeFgHiJkLmNoPqRsTu", + "image_url": "https://example.com", + "kind": "Solution", + "latest_solution": "id_0aBcDeFgHiJkLmNoPqRsTu", + "latest_version": "1.0.0", + "lookup_key": "string", + "metadata": { + "key": "value" + }, + "name": "Example Name", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "org_logo": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + }, + "org_name": "Example Name", + "org_slug": "example-slug", + "owners": [ + "string" + ], + "readme_url": "https://example.com", + "screenshot_urls": [ + "https://example.com" + ], + "solution_id": "01234567-89ab-cdef-0123-456789abcdef", + "solution_version": "1.2.0", + "tag_keys": [ + "string" + ], + "template_kind": "AgentTemplate", + "templates": [ + { + "description": "An example description.", + "display_name": "Example Name", + "id": "id_0aBcDeFgHiJkLmNoPqRsTu", + "kind": "AgentTemplate", + "lookup_key": "string", + "name": "Example Name", + "readme_url": "https://example.com", + "virtual_path": "string" + } + ], + "updated_at": "2024-01-01T00:00:00Z", + "upgrade_available": true, + "virtual_path": "string" + }, + "solution": { + "category_keys": [ + "string" + ], + "created_at": "2024-01-01T00:00:00Z", + "description": "An example description.", + "events": {}, + "id": "id_0aBcDeFgHiJkLmNoPqRsTu", + "image_url": "https://example.com", + "kind": "Solution", + "latest_solution": "id_0aBcDeFgHiJkLmNoPqRsTu", + "latest_version": "1.0.0", + "lookup_key": "string", + "metadata": { + "key": "value" + }, + "name": "Example Name", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "org_logo": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + }, + "org_name": "Example Name", + "org_slug": "example-slug", + "owners": [ + "string" + ], + "readme_url": "https://example.com", + "screenshot_urls": [ + "https://example.com" + ], + "solution_id": "01234567-89ab-cdef-0123-456789abcdef", + "solution_version": "1.2.0", + "tag_keys": [ + "string" + ], + "template_kind": "AgentTemplate", + "templates": [ + { + "description": "An example description.", + "display_name": "Example Name", + "id": "id_0aBcDeFgHiJkLmNoPqRsTu", + "kind": "AgentTemplate", + "lookup_key": "string", + "name": "Example Name", + "readme_url": "https://example.com", + "virtual_path": "string" + } + ], + "updated_at": "2024-01-01T00:00:00Z", + "upgrade_available": true, + "virtual_path": "string" + }, + "template": { + "created_at": "2024-01-01T00:00:00Z", + "description": "An example description.", + "display_name": "Example Name", + "id": "id_0aBcDeFgHiJkLmNoPqRsTu", + "kind": "agent_tool_template", + "lookup_key": "string", + "name": "Example Name", + "updated_at": "2024-01-01T00:00:00Z", + "virtual_path": "string" + } + }, + "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "template_upgrade_available": true, + "updated_at": "2024-01-01T00:00:00Z", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" + }, + "nullable": true }, "created_at": { "description": "When this membership record was created (ISO 8601).", @@ -17576,11 +19664,26 @@ "name": { "description": "Display name of the member, derived from the associated user or agent. `null` if the principal is unknown.", "example": "Example Name", + "nullable": true, "type": "string" }, "profile_picture": { - "$ref": "#/components/schemas/ImageSource", - "description": "Profile picture of the member, derived from the associated user or agent. `null` if not set or principal is unknown." + "allOf": [ + { + "$ref": "#/components/schemas/ImageSource" + } + ], + "description": "Profile picture of the member, derived from the associated user or agent. `null` if not set or principal is unknown.", + "example": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + }, + "nullable": true }, "role": { "description": "The member's role within the team. One of `\"owner\"`, `\"admin\"`, or `\"member\"`.", @@ -17590,6 +19693,7 @@ "team": { "description": "The team this membership belongs to, as an expanded team object. `null` when the team association is not preloaded.", "example": {}, + "nullable": true, "type": "object" }, "type": { @@ -17604,8 +19708,36 @@ "type": "string" }, "user": { - "$ref": "#/components/schemas/User", - "description": "The user associated with this membership, as an expanded user object. `null` when the member is an agent, the type is unknown, or the association is not preloaded." + "allOf": [ + { + "$ref": "#/components/schemas/User" + } + ], + "description": "The user associated with this membership, as an expanded user object. `null` when the member is an agent, the type is unknown, or the association is not preloaded.", + "example": { + "alias": "jdoe", + "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "email": "user@example.com", + "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "is_system_user": true, + "metadata": { + "key": "value" + }, + "name": "Example Name", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "org_name": "Example Name", + "org_role": "member", + "org_slug": "example-slug", + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "sandbox_name": "Example Name" + }, + "nullable": true } }, "required": [ @@ -17823,6 +19955,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -17833,6 +19970,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -17893,7 +20031,7 @@ "description": "A chat thread, representing a conversation channel that can be owned by a user, team, or agent and may contain messages, participants, and AI agent activity.", "example": { "agent_user": "agi_0aBcDeFgHiJkLmNoPqRsTu", - "created_at": "2024-01-01T00:00:00Z", + "created_at": "string", "creator": "usr_0aBcDeFgHiJkLmNoPqRsTu", "description": "An example description.", "id": "string", @@ -17903,7 +20041,7 @@ "is_unlisted": true, "key": "string", "kind": "string", - "last_activity": "2024-01-01T00:00:00Z", + "last_activity": "string", "last_message_preview": "Sounds good — I'll ship the fix tomorrow.", "last_message_sender": "Alice Chen", "metadata": { @@ -18044,7 +20182,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "participant": [ @@ -18055,6 +20193,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -18065,6 +20208,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -18270,9 +20414,9 @@ ], "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "title": "Example Title", - "ttl": 3600, + "ttl": "2026-08-15T12:00:00", "unread_count": 5, - "updated_at": "2024-01-01T00:00:00Z", + "updated_at": "string", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "team" }, @@ -18280,17 +20424,18 @@ "agent_user": { "description": "ID of the agent that owns this thread (`agt_...`). `null` for user-owned or team-owned threads.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "created_at": { "description": "When the thread was created (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "creator": { "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.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "oneOf": [ { "type": "string" @@ -18301,6 +20446,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -18311,6 +20461,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" }, @@ -18318,21 +20469,55 @@ "alias": { "description": "Short handle or alias for the user. `null` if not set.", "example": "jdoe", + "nullable": true, "type": "string" }, "app": { "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.", "example": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "app_name": { "description": "Display name of the user's app. `null` when the app association was not preloaded by the caller.", "example": "Example Name", + "nullable": true, + "type": "string" + }, + "created_by_agent_user": { + "description": "Agent user that created this account (`usr_...`). `null` unless an agent created it.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_developer": { + "description": "Developer account that created this user (`dva_...`). `null` unless created via a developer token.", + "example": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_org": { + "description": "Org of the principal that created this user (`org_...`). `null` on legacy rows.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_team": { + "description": "Team that created this user (`tem_...`). `null` unless created as a team.", + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_user": { + "description": "User who created this account (`usr_...`). `null` on self-signup or legacy rows.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "email": { "description": "Email address of the user.", "example": "user@example.com", + "nullable": true, "type": "string" }, "id": { @@ -18355,31 +20540,43 @@ "name": { "description": "Full display name of the user. `null` if the user has not set a name.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "description": "ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_name": { "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.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_role": { "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.", "example": "member", + "nullable": true, + "type": "string" + }, + "org_slug": { + "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.", + "example": "example-slug", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "sandbox_name": { "description": "Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.", "example": "Example Name", + "nullable": true, "type": "string" } }, @@ -18393,6 +20590,7 @@ "description": { "description": "Optional description or purpose statement for the thread. `null` if not set.", "example": "An example description.", + "nullable": true, "type": "string" }, "id": { @@ -18423,27 +20621,31 @@ "key": { "description": "Application-defined stable key that uniquely identifies the thread within its scope. Useful for idempotent creation. `null` if not set.", "example": "string", + "nullable": true, "type": "string" }, "kind": { - "description": "Thread subtype: `\"standard\"` for ordinary threads, `\"slack_mirror\"` for the membership-strict mirror of a Slack channel, `\"slashwork_mirror\"` for the membership-strict mirror of a Slashwork group. Read-only — derived server-side at creation, never accepted from params.", + "description": "Thread subtype: `\"standard\"` for ordinary threads, `\"personal\"` for a user-and-owned-agents roster, `\"slack_mirror\"` for the membership-strict mirror of a Slack channel, or `\"slashwork_mirror\"` for the membership-strict mirror of a Slashwork group. `personal` is an explicit user-thread creation option; mirror kinds are server-derived.", "example": "string", + "nullable": true, "type": "string" }, "last_activity": { "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.", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", + "nullable": true, "type": "string" }, "last_message_preview": { "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.", "example": "Sounds good — I'll ship the fix tomorrow.", + "nullable": true, "type": "string" }, "last_message_sender": { "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.", "example": "Alice Chen", + "nullable": true, "type": "string" }, "metadata": { @@ -18451,6 +20653,7 @@ "example": { "key": "value" }, + "nullable": true, "type": "object" }, "muted": { @@ -18461,11 +20664,153 @@ "org": { "description": "ID of the organization this thread belongs to (`org_...`). `null` for threads outside an org context.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "parent_message": { - "$ref": "#/components/schemas/Message", - "description": "The message that spawned this thread as a sub-thread. `null` for top-level threads." + "allOf": [ + { + "$ref": "#/components/schemas/Message" + } + ], + "description": "The message that spawned this thread as a sub-thread. `null` for top-level threads.", + "example": { + "acl": { + "add": [ + { + "actions": [ + "read", + "write" + ], + "principal": "string", + "principal_type": "user" + } + ], + "grants": [ + { + "actions": [ + "read", + "write" + ], + "principal": "string", + "principal_type": "user" + } + ], + "remove": [ + { + "principal": "string", + "principal_type": "user" + } + ] + }, + "actors": [ + { + "alias": "alice", + "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "name": "Example Name", + "profile_picture": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + } + } + ], + "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "agent_mode": "cli", + "attachments": [ + { + "content_type": "application/json", + "description": "An example description.", + "filename": "string", + "height": 1, + "id": "string", + "image_height": 1, + "image_source": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + }, + "image_url": "https://example.com", + "image_width": 1, + "media_type": "application/json", + "name": "Example Name", + "object": {}, + "title": "Example Title", + "type": "file", + "url": "https://example.com", + "variants": [ + { + "content_type": "application/json", + "created_at": "2024-01-01T00:00:00Z", + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "filename": "string", + "height": 600, + "id": "mvr_0aBcDeFgHiJkLmNoPqRsTu", + "image_source": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + }, + "updated_at": "2024-01-01T00:00:00Z", + "url": "https://example.com", + "variant_key": "original", + "width": 800 + } + ], + "version": 1, + "width": 1 + } + ], + "branched_thread": "string", + "content": "Hello, how can I help you today?", + "created_at": "2024-01-01T00:00:00Z", + "has_replies": true, + "id": "msg_0aBcDeFgHiJkLmNoPqRsTu", + "idempotency_key": "01234567-89ab-cdef-0123-456789abcdef", + "is_deleted": true, + "legacy_agent": "string", + "metadata": { + "key": "value" + }, + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "reactions": [ + { + "payload": { + "key": "value" + }, + "type": "emoji_reaction", + "user": "string" + } + ], + "rendering_mode": "reply", + "replies": [ + {} + ], + "replies_after_cursor": "string", + "replies_before_cursor": "string", + "reply_count": 1, + "reply_to": {}, + "root_message_id": "string", + "sandbox": "string", + "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "thread": "string", + "type": "note", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "visibility": "default" + }, + "nullable": true }, "participant": { "description": "Array of participant user IDs (`usr_...`) who are members of this thread.", @@ -18496,19 +20841,210 @@ }, "participating_agents": { "description": "Expanded agent objects for all agents participating in this thread. Present only when agent enrichment is requested.", + "example": [ + { + "acl": { + "add": [ + { + "actions": [ + "read", + "write" + ], + "principal": "string", + "principal_type": "user" + } + ], + "grants": [ + { + "actions": [ + "read", + "write" + ], + "principal": "string", + "principal_type": "user" + } + ], + "remove": [ + { + "principal": "string", + "principal_type": "user" + } + ] + }, + "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "created_at": "2024-01-01T00:00:00Z", + "default_model": "claude-3-7-sonnet-latest", + "description": "An example description.", + "email": "user@example.com", + "id": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "identity": "You are a helpful assistant that answers questions about ArchAstro products.", + "last_applied_template_config": "cfg_0aBcDeFgHiJkLmNoPqRsTu", + "lookup_key": "string", + "metadata": { + "key": "value" + }, + "name": "Example Name", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "org_name": "Example Name", + "originator": "deploy-pipeline", + "phone_number": "+15555550123", + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_solution": { + "current_solution": { + "category_keys": [ + "string" + ], + "created_at": "2024-01-01T00:00:00Z", + "description": "An example description.", + "events": {}, + "id": "id_0aBcDeFgHiJkLmNoPqRsTu", + "image_url": "https://example.com", + "kind": "Solution", + "latest_solution": "id_0aBcDeFgHiJkLmNoPqRsTu", + "latest_version": "1.0.0", + "lookup_key": "string", + "metadata": { + "key": "value" + }, + "name": "Example Name", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "org_logo": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + }, + "org_name": "Example Name", + "org_slug": "example-slug", + "owners": [ + "string" + ], + "readme_url": "https://example.com", + "screenshot_urls": [ + "https://example.com" + ], + "solution_id": "01234567-89ab-cdef-0123-456789abcdef", + "solution_version": "1.2.0", + "tag_keys": [ + "string" + ], + "template_kind": "AgentTemplate", + "templates": [ + { + "description": "An example description.", + "display_name": "Example Name", + "id": "id_0aBcDeFgHiJkLmNoPqRsTu", + "kind": "AgentTemplate", + "lookup_key": "string", + "name": "Example Name", + "readme_url": "https://example.com", + "virtual_path": "string" + } + ], + "updated_at": "2024-01-01T00:00:00Z", + "upgrade_available": true, + "virtual_path": "string" + }, + "solution": { + "category_keys": [ + "string" + ], + "created_at": "2024-01-01T00:00:00Z", + "description": "An example description.", + "events": {}, + "id": "id_0aBcDeFgHiJkLmNoPqRsTu", + "image_url": "https://example.com", + "kind": "Solution", + "latest_solution": "id_0aBcDeFgHiJkLmNoPqRsTu", + "latest_version": "1.0.0", + "lookup_key": "string", + "metadata": { + "key": "value" + }, + "name": "Example Name", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "org_logo": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + }, + "org_name": "Example Name", + "org_slug": "example-slug", + "owners": [ + "string" + ], + "readme_url": "https://example.com", + "screenshot_urls": [ + "https://example.com" + ], + "solution_id": "01234567-89ab-cdef-0123-456789abcdef", + "solution_version": "1.2.0", + "tag_keys": [ + "string" + ], + "template_kind": "AgentTemplate", + "templates": [ + { + "description": "An example description.", + "display_name": "Example Name", + "id": "id_0aBcDeFgHiJkLmNoPqRsTu", + "kind": "AgentTemplate", + "lookup_key": "string", + "name": "Example Name", + "readme_url": "https://example.com", + "virtual_path": "string" + } + ], + "updated_at": "2024-01-01T00:00:00Z", + "upgrade_available": true, + "virtual_path": "string" + }, + "template": { + "created_at": "2024-01-01T00:00:00Z", + "description": "An example description.", + "display_name": "Example Name", + "id": "id_0aBcDeFgHiJkLmNoPqRsTu", + "kind": "agent_tool_template", + "lookup_key": "string", + "name": "Example Name", + "updated_at": "2024-01-01T00:00:00Z", + "virtual_path": "string" + } + }, + "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "template_upgrade_available": true, + "updated_at": "2024-01-01T00:00:00Z", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" + } + ], "items": { - "$ref": "#/components/schemas/Agent" + "allOf": [ + { + "$ref": "#/components/schemas/Agent" + } + ], + "nullable": true }, + "nullable": true, "type": "array" }, "role": { "description": "The authenticated user's membership role in this thread, e.g. `\"owner\"`, `\"member\"`, or `\"viewer\"`. `null` if the user is not a member.", "example": "member", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the developer sandbox this thread is scoped to (`dsb_...`). `null` for production threads.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "settings": { @@ -18518,6 +21054,7 @@ "slug": { "description": "URL-safe slug for the thread, used in human-readable permalinks. `null` if not assigned.", "example": "example-slug", + "nullable": true, "type": "string" }, "sub_threads": { @@ -18526,8 +21063,10 @@ {} ], "items": { + "nullable": true, "type": "object" }, + "nullable": true, "type": "array" }, "tags": { @@ -18544,32 +21083,36 @@ "team": { "description": "ID of the team that owns this thread (`team_...`). `null` for user-owned or agent-owned threads.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "title": { "description": "Human-readable name of the thread. `null` if no title has been set.", "example": "Example Title", + "nullable": true, "type": "string" }, "ttl": { - "description": "Time-to-live in seconds after which the thread may be automatically cleaned up. `null` if the thread does not expire.", - "example": 3600, - "type": "integer" + "description": "Offset-free expiry timestamp after which the thread may be automatically cleaned up. `null` if the thread does not expire.", + "example": "2026-08-15T12:00:00", + "nullable": true, + "type": "string" }, "unread_count": { "description": "Number of messages in this thread that the authenticated user has not yet read. Present only when read-state enrichment is requested.", "example": 5, + "nullable": true, "type": "integer" }, "updated_at": { "description": "When the thread was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "user": { "description": "ID of the user who owns this thread (`usr_...`). `null` for team-owned or agent-owned threads.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "visibility": { @@ -18850,8 +21393,9 @@ }, "properties": { "agent_enabled": { - "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.", + "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.", "example": true, + "nullable": true, "type": "boolean" } }, @@ -18860,24 +21404,25 @@ "Trajectory": { "description": "A recorded sequence of AI messages and tool interactions representing a single AI reasoning session. Trajectories are stored as structured message logs and can be replayed or inspected after execution.", "example": { - "created_at": "2024-01-01T00:00:00Z", + "created_at": "string", "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", "id": "trj_0aBcDeFgHiJkLmNoPqRsTu", - "messages": {}, + "messages": [ + {} + ], "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", - "updated_at": "2024-01-01T00:00:00Z" + "updated_at": "string" }, "properties": { "created_at": { "description": "When the trajectory was recorded (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "file": { - "description": "ID of the storage file that persists the raw trajectory data (`fil_...`). `null` if the trajectory has not been written to a file.", + "description": "ID of the storage file that persists the raw trajectory data (`fil_...`).", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", "type": "string" }, @@ -18888,28 +21433,35 @@ }, "messages": { "description": "Serialized message log for this trajectory. Contains the ordered sequence of AI and tool messages produced during the session.", - "example": {}, - "type": "object" + "example": [ + {} + ], + "items": { + "type": "object" + }, + "type": "array" }, "org": { "description": "ID of the organization this trajectory belongs to (`org_...`). `null` for trajectories outside an org context.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the developer sandbox this trajectory is scoped to (`sbx_...`). `null` for production trajectories.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "team": { "description": "ID of the team this trajectory is scoped to (`team_...`). `null` for trajectories not associated with a team.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "updated_at": { "description": "When the trajectory record was last updated (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" } }, @@ -18941,11 +21493,13 @@ "description": { "description": "Description of the template from the config body. `null` if the current version has no `description` field.", "example": "An example description.", + "nullable": true, "type": "string" }, "display_name": { "description": "Human-readable display name from the config body. `null` if the current version has no `display_name` field.", "example": "Example Name", + "nullable": true, "type": "string" }, "id": { @@ -18961,11 +21515,13 @@ "lookup_key": { "description": "Stable lookup key assigned to this template config. `null` if no lookup key is set.", "example": "string", + "nullable": true, "type": "string" }, "name": { "description": "Template name as stored in the config body. `null` if the current version has no `name` field.", "example": "Example Name", + "nullable": true, "type": "string" }, "updated_at": { @@ -18977,6 +21533,7 @@ "virtual_path": { "description": "Virtual filesystem path for this template config. `null` if not set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -18992,6 +21549,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -19002,6 +21564,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" }, @@ -19009,21 +21572,55 @@ "alias": { "description": "Short handle or alias for the user. `null` if not set.", "example": "jdoe", + "nullable": true, "type": "string" }, "app": { "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.", "example": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "app_name": { "description": "Display name of the user's app. `null` when the app association was not preloaded by the caller.", "example": "Example Name", + "nullable": true, + "type": "string" + }, + "created_by_agent_user": { + "description": "Agent user that created this account (`usr_...`). `null` unless an agent created it.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_developer": { + "description": "Developer account that created this user (`dva_...`). `null` unless created via a developer token.", + "example": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_org": { + "description": "Org of the principal that created this user (`org_...`). `null` on legacy rows.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_team": { + "description": "Team that created this user (`tem_...`). `null` unless created as a team.", + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_user": { + "description": "User who created this account (`usr_...`). `null` on self-signup or legacy rows.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "email": { "description": "Email address of the user.", "example": "user@example.com", + "nullable": true, "type": "string" }, "id": { @@ -19046,31 +21643,43 @@ "name": { "description": "Full display name of the user. `null` if the user has not set a name.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "description": "ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_name": { "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.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_role": { "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.", "example": "member", + "nullable": true, + "type": "string" + }, + "org_slug": { + "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.", + "example": "example-slug", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "sandbox_name": { "description": "Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.", "example": "Example Name", + "nullable": true, "type": "string" } }, @@ -19973,7 +22582,7 @@ ] }, "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", - "created_at": "2024-01-01T00:00:00Z", + "created_at": "string", "default_model": "claude-3-7-sonnet-latest", "description": "An example description.", "email": "user@example.com", @@ -20121,7 +22730,7 @@ }, "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "template_upgrade_available": true, - "updated_at": "2024-01-01T00:00:00Z", + "updated_at": "string", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" }, "properties": { @@ -20155,6 +22764,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -20305,23 +22915,25 @@ }, "created_at": { "description": "When the agent was created (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "default_model": { "description": "Default LLM model identifier used by this agent when no model is specified at runtime (e.g. `\"claude-3-7-sonnet-latest\"`).", "example": "claude-3-7-sonnet-latest", + "nullable": true, "type": "string" }, "description": { "description": "Human-readable description of what the agent does. `null` if not set.", "example": "An example description.", + "nullable": true, "type": "string" }, "email": { "description": "Email address provisioned for this agent. `null` if email delivery is not configured.", "example": "user@example.com", + "nullable": true, "type": "string" }, "id": { @@ -20332,16 +22944,19 @@ "identity": { "description": "System-level identity prompt that shapes the agent's persona and behavior.", "example": "You are a helpful assistant that answers questions about ArchAstro products.", + "nullable": true, "type": "string" }, "last_applied_template_config": { "description": "ID of the AgentTemplate config (`cfg_...`) this agent was last provisioned or updated from. `null` for manually created agents.", "example": "cfg_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "lookup_key": { "description": "Stable, user-defined identifier for this agent within the application. Unique per app.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -20359,26 +22974,31 @@ "org": { "description": "ID of the organization this agent belongs to (`org_...`). `null` if the agent is not org-scoped.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_name": { "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.", "example": "Example Name", + "nullable": true, "type": "string" }, "originator": { "description": "Free-form label identifying the source or author that created this agent (e.g. a username or pipeline name).", "example": "deploy-pipeline", + "nullable": true, "type": "string" }, "phone_number": { "description": "Phone number provisioned for this agent. `null` if SMS is not configured.", "example": "+15555550123", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the sandbox environment this agent is scoped to (`dsb_...`). `null` in production deployments.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "source_solution": { @@ -20512,6 +23132,7 @@ "virtual_path": "string" } }, + "nullable": true, "properties": { "current_solution": { "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.", @@ -20586,13 +23207,13 @@ }, "created_at": { "description": "When the Solution config was first imported (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "events": { @@ -20608,6 +23229,7 @@ "image_url": { "description": "Absolute URL of the Solution's cover image — the bundled asset the body's `image:` field names. A stable, non-expiring capability URL (like `org_logo.url`), safe to hold in caches and OpenGraph tags; it 404s if the Solution stops declaring a cover. `null` when the Solution has no cover image, and always `null` for org-scoped rows — the permanent URL is minted for system-scope (catalog) Solutions only.", "example": "https://example.com", + "nullable": true, "type": "string" }, "kind": { @@ -20618,16 +23240,19 @@ "latest_solution": { "description": "When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "latest_version": { "description": "When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", "example": "1.0.0", + "nullable": true, "type": "string" }, "lookup_key": { "description": "The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -20640,11 +23265,13 @@ "name": { "description": "Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "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.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_logo": { @@ -20658,40 +23285,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -20700,11 +23335,13 @@ "org_name": { "description": "Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_slug": { "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.", "example": "example-slug", + "nullable": true, "type": "string" }, "owners": { @@ -20720,6 +23357,7 @@ "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "screenshot_urls": { @@ -20735,11 +23373,13 @@ "solution_id": { "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.", "example": "01234567-89ab-cdef-0123-456789abcdef", + "nullable": true, "type": "string" }, "solution_version": { "description": "Semver string declared in the Solution body (e.g. `\"1.2.0\"`). `null` when the body does not declare a version.", "example": "1.2.0", + "nullable": true, "type": "string" }, "tag_keys": { @@ -20755,6 +23395,7 @@ "template_kind": { "description": "Wrapped template kind — `\"AgentTemplate\"`, `\"AutomationTemplate\"`, `\"AgentRoutineTemplate\"`, `\"AgentToolTemplate\"`, `\"AgentComputerTemplate\"`, or `\"SolutionTemplateRef\"` for ref-mode bundles.", "example": "AgentTemplate", + "nullable": true, "type": "string" }, "templates": { @@ -20787,6 +23428,7 @@ "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "details": { @@ -20794,6 +23436,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -20818,12 +23461,13 @@ }, "properties": { "automation_type": { - "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`).", + "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", "example": "string", + "nullable": true, "type": "string" }, "invoke_contract": { - "description": "Schema-driven payload and participant inputs for an invoked automation. Used by installation clients to collect locked prefills before provisioning.", + "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.", "example": { "input_schema": {}, "participants": [ @@ -20839,10 +23483,12 @@ "payload": {} } }, + "nullable": true, "properties": { "input_schema": { "description": "JSON Schema validated against the whole invoke payload, from the automation's `input_schema_config`. `null` when none is configured.", "example": {}, + "nullable": true, "type": "object" }, "participants": { @@ -20863,10 +23509,12 @@ "required": true, "type": "agent_user" }, + "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", "example": "An example description.", + "nullable": true, "type": "string" }, "name": { @@ -20892,6 +23540,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -20940,11 +23589,13 @@ "display_name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "id": { "description": "Template config ID (`cfg_...`). `null` for inline-only templates.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "kind": { @@ -20955,21 +23606,25 @@ "lookup_key": { "description": "Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", "example": "string", + "nullable": true, "type": "string" }, "name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "virtual_path": { "description": "Stable virtual path assigned to the template config. `null` when no virtual path was set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -20982,8 +23637,7 @@ }, "updated_at": { "description": "When the Solution config was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "upgrade_available": { @@ -20994,6 +23648,7 @@ "virtual_path": { "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.", "example": "string", + "nullable": true, "type": "string" } }, @@ -21079,13 +23734,13 @@ }, "created_at": { "description": "When the Solution config was first imported (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "events": { @@ -21101,6 +23756,7 @@ "image_url": { "description": "Absolute URL of the Solution's cover image — the bundled asset the body's `image:` field names. A stable, non-expiring capability URL (like `org_logo.url`), safe to hold in caches and OpenGraph tags; it 404s if the Solution stops declaring a cover. `null` when the Solution has no cover image, and always `null` for org-scoped rows — the permanent URL is minted for system-scope (catalog) Solutions only.", "example": "https://example.com", + "nullable": true, "type": "string" }, "kind": { @@ -21111,16 +23767,19 @@ "latest_solution": { "description": "When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "latest_version": { "description": "When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", "example": "1.0.0", + "nullable": true, "type": "string" }, "lookup_key": { "description": "The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -21133,11 +23792,13 @@ "name": { "description": "Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "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.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_logo": { @@ -21151,40 +23812,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -21193,11 +23862,13 @@ "org_name": { "description": "Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_slug": { "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.", "example": "example-slug", + "nullable": true, "type": "string" }, "owners": { @@ -21213,6 +23884,7 @@ "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "screenshot_urls": { @@ -21228,11 +23900,13 @@ "solution_id": { "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.", "example": "01234567-89ab-cdef-0123-456789abcdef", + "nullable": true, "type": "string" }, "solution_version": { "description": "Semver string declared in the Solution body (e.g. `\"1.2.0\"`). `null` when the body does not declare a version.", "example": "1.2.0", + "nullable": true, "type": "string" }, "tag_keys": { @@ -21248,6 +23922,7 @@ "template_kind": { "description": "Wrapped template kind — `\"AgentTemplate\"`, `\"AutomationTemplate\"`, `\"AgentRoutineTemplate\"`, `\"AgentToolTemplate\"`, `\"AgentComputerTemplate\"`, or `\"SolutionTemplateRef\"` for ref-mode bundles.", "example": "AgentTemplate", + "nullable": true, "type": "string" }, "templates": { @@ -21280,6 +23955,7 @@ "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "details": { @@ -21287,6 +23963,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -21311,12 +23988,13 @@ }, "properties": { "automation_type": { - "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`).", + "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", "example": "string", + "nullable": true, "type": "string" }, "invoke_contract": { - "description": "Schema-driven payload and participant inputs for an invoked automation. Used by installation clients to collect locked prefills before provisioning.", + "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.", "example": { "input_schema": {}, "participants": [ @@ -21332,10 +24010,12 @@ "payload": {} } }, + "nullable": true, "properties": { "input_schema": { "description": "JSON Schema validated against the whole invoke payload, from the automation's `input_schema_config`. `null` when none is configured.", "example": {}, + "nullable": true, "type": "object" }, "participants": { @@ -21356,10 +24036,12 @@ "required": true, "type": "agent_user" }, + "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", "example": "An example description.", + "nullable": true, "type": "string" }, "name": { @@ -21385,6 +24067,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -21433,11 +24116,13 @@ "display_name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "id": { "description": "Template config ID (`cfg_...`). `null` for inline-only templates.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "kind": { @@ -21448,21 +24133,25 @@ "lookup_key": { "description": "Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", "example": "string", + "nullable": true, "type": "string" }, "name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "virtual_path": { "description": "Stable virtual path assigned to the template config. `null` when no virtual path was set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -21475,8 +24164,7 @@ }, "updated_at": { "description": "When the Solution config was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "upgrade_available": { @@ -21487,6 +24175,7 @@ "virtual_path": { "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.", "example": "string", + "nullable": true, "type": "string" } }, @@ -21522,11 +24211,13 @@ "description": { "description": "Description of the template from the config body. `null` if the current version has no `description` field.", "example": "An example description.", + "nullable": true, "type": "string" }, "display_name": { "description": "Human-readable display name from the config body. `null` if the current version has no `display_name` field.", "example": "Example Name", + "nullable": true, "type": "string" }, "id": { @@ -21542,11 +24233,13 @@ "lookup_key": { "description": "Stable lookup key assigned to this template config. `null` if no lookup key is set.", "example": "string", + "nullable": true, "type": "string" }, "name": { "description": "Template name as stored in the config body. `null` if the current version has no `name` field.", "example": "Example Name", + "nullable": true, "type": "string" }, "updated_at": { @@ -21558,6 +24251,7 @@ "virtual_path": { "description": "Virtual filesystem path for this template config. `null` if not set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -21577,22 +24271,24 @@ "team": { "description": "ID of the team that owns this agent (`tem_...`). `null` if the agent is not team-scoped.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "template_upgrade_available": { "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`).", "example": true, + "nullable": true, "type": "boolean" }, "updated_at": { "description": "When the agent was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "user": { "description": "ID of the user that owns this agent (`usr_...`). `null` if the agent is not user-scoped.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" } }, @@ -21715,6 +24411,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -21725,6 +24426,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" }, @@ -21732,21 +24434,55 @@ "alias": { "description": "Short handle or alias for the user. `null` if not set.", "example": "jdoe", + "nullable": true, "type": "string" }, "app": { "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.", "example": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "app_name": { "description": "Display name of the user's app. `null` when the app association was not preloaded by the caller.", "example": "Example Name", + "nullable": true, + "type": "string" + }, + "created_by_agent_user": { + "description": "Agent user that created this account (`usr_...`). `null` unless an agent created it.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_developer": { + "description": "Developer account that created this user (`dva_...`). `null` unless created via a developer token.", + "example": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_org": { + "description": "Org of the principal that created this user (`org_...`). `null` on legacy rows.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_team": { + "description": "Team that created this user (`tem_...`). `null` unless created as a team.", + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_user": { + "description": "User who created this account (`usr_...`). `null` on self-signup or legacy rows.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "email": { "description": "Email address of the user.", "example": "user@example.com", + "nullable": true, "type": "string" }, "id": { @@ -21769,31 +24505,43 @@ "name": { "description": "Full display name of the user. `null` if the user has not set a name.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "description": "ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_name": { "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.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_role": { "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.", "example": "member", + "nullable": true, + "type": "string" + }, + "org_slug": { + "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.", + "example": "example-slug", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "sandbox_name": { "description": "Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.", "example": "Example Name", + "nullable": true, "type": "string" } }, @@ -28990,6 +31738,7 @@ "description": "An example description.", "is_unlisted": true, "key": "string", + "kind": "personal", "members": [ { "id": "string", @@ -29027,6 +31776,7 @@ "description": "An example description.", "is_unlisted": true, "key": "string", + "kind": "personal", "members": [ { "id": "string", @@ -29071,6 +31821,14 @@ "example": "string", "type": "string" }, + "kind": { + "description": "Optional behavioral subtype. `personal` is accepted only for a user-owned thread and limits membership to that user and agents currently owned by them. Mirror kinds remain server-derived and cannot be selected by callers.", + "enum": [ + "personal" + ], + "example": "personal", + "type": "string" + }, "members": { "description": "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.", "example": [ @@ -29159,8 +31917,9 @@ }, "properties": { "agent_enabled": { - "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.", + "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.", "example": true, + "nullable": true, "type": "boolean" } }, @@ -30580,6 +33339,9 @@ }, "401": { "description": "Unauthorized" + }, + "403": { + "description": "Forbidden — app scope required" } }, "summary": "List available AI models", @@ -31692,6 +34454,7 @@ "full_name": "Example Name", "invite_code": "string", "password": "string", + "set_org": true, "team_invite": "string", "timezone": "America/New_York" }, @@ -31721,6 +34484,11 @@ "example": "string", "type": "string" }, + "set_org": { + "description": "Create or reuse an organization from the work-email domain and stamp the new user into it.", + "example": true, + "type": "boolean" + }, "team_invite": { "description": "Team invite ID. When provided, the user is added to the team on registration.", "example": "string", @@ -31788,6 +34556,7 @@ "email": "user@example.com", "full_name": "Example Name", "redirect_uri": "https://example.com", + "set_org": true, "timezone": "America/New_York" }, "properties": { @@ -31811,6 +34580,11 @@ "example": "https://example.com", "type": "string" }, + "set_org": { + "description": "Create or reuse an organization from the work-email domain during confirmation.", + "example": true, + "type": "boolean" + }, "timezone": { "description": "IANA timezone name for the new account, e.g. `\"America/New_York\"`.", "example": "America/New_York", @@ -31858,7 +34632,8 @@ "schema": { "example": { "email": "user@example.com", - "redirect_uri": "https://example.com" + "redirect_uri": "https://example.com", + "set_org": true }, "properties": { "email": { @@ -31870,6 +34645,11 @@ "description": "URL the user is redirected to after clicking the magic link. Must be registered with the app.", "example": "https://example.com", "type": "string" + }, + "set_org": { + "description": "For a new user, create or reuse an organization from the work-email domain during confirmation.", + "example": true, + "type": "boolean" } }, "type": "object" @@ -35988,77 +38768,178 @@ ] } }, - "/api/v1/extractions": { + "/api/v1/event_subscription_deliveries/{delivery}/acknowledge": { "post": { - "description": "Records a text-extraction job for a document (`file`) or a URL (`url` + `mode`).\nThe job is owner-scoped and tagged with the caller-supplied `destination`\nnamespace, **without** committing knowledge to an agent (no embeddings, no\nagent attach).\n\nExactly one of `file` or (`url` + `mode`) is required.\n\nDocument extraction (`file`) runs synchronously: the response already\nreflects the final state (`done` with its output, or an error if extraction\ncouldn't complete), status `201`. URL extraction (`url` + `mode`) submits an\nasync crawl and returns immediately with state `running`, status `202` —\npoll `GET /extractions/:extraction` for its terminal state.\n", - "operationId": "post_api_v1_extractions", - "parameters": [], + "description": "Acknowledges a delivery using its current receipt handle. Repeating the same acknowledgement is idempotent; a stale or incorrect receipt returns 409. Acknowledging a delivery that aged out under the subscription's retention returns `delivery_not_found` — the event was already counted in `dropped_events_total`, and the acknowledgement should not be retried.", + "operationId": "post_api_v1_event_subscription_deliveries__delivery_acknowledge", + "parameters": [ + { + "description": "Delivery ID (`esd_...`).", + "example": "string", + "in": "path", + "name": "delivery", + "required": true, + "schema": { + "type": "string" + } + } + ], "requestBody": { "content": { "application/json": { "schema": { "example": { - "agent": "string", - "destination_kind": "config", - "destination_path": "string", - "file": "string", - "max_pages": 1, - "mode": "link", - "org": "string", - "url": "https://example.com" + "receipt_handle": "string" }, "properties": { - "agent": { - "description": "Owning agent (`agt_...`) — scopes the extraction and its outputs.", + "receipt_handle": { + "description": "Opaque handle returned by claim.", "example": "string", "type": "string" - }, - "destination_kind": { - "description": "Where outputs are written.", - "enum": [ - "config", - "storage" + } + }, + "required": [ + "receipt_handle" + ], + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "204": { + "description": "No content" + }, + "401": { + "description": "Unauthorized" + }, + "404": { + "description": "Event subscription delivery not found" + }, + "409": { + "description": "The delivery lease is no longer current" + } + }, + "summary": "Acknowledge a claimed event", + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/event_subscriptions": { + "get": { + "description": "Lists the subscriptions visible to the caller, with current queue counters.", + "operationId": "get_api_v1_event_subscriptions", + "parameters": [ + { + "description": "Page number, starting at 1.", + "example": 1, + "in": "query", + "name": "page", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "description": "Subscriptions per page, from 1 through 100.", + "example": 1, + "in": "query", + "name": "per_page", + "required": false, + "schema": { + "type": "integer" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EventSubscriptionPage" + } + } + }, + "description": "Subscriptions visible to this caller." + }, + "401": { + "description": "Unauthorized" + }, + "422": { + "description": "Invalid parameters" + } + }, + "summary": "List domain-event subscriptions", + "x-auth": [ + "publishable_key", + "bearer" + ] + }, + "post": { + "description": "Creates a durable subscription that receives exportable domain events matching its exact event names. Matching events fan out into a per-subscription queue bounded by max_pending_events and retention_seconds; consume with claim and acknowledge.", + "operationId": "post_api_v1_event_subscriptions", + "parameters": [], + "requestBody": { + "content": { + "application/json": { + "schema": { + "example": { + "event_names": [ + "Example Name" + ], + "max_pending_events": 1, + "name": "Example Name", + "retention_seconds": 1, + "status": "active", + "visibility_timeout_seconds": 1 + }, + "properties": { + "event_names": { + "description": "Exact event names to receive.", + "example": [ + "Example Name" ], - "example": "config", - "type": "string" + "items": { + "type": "string" + }, + "type": "array" }, - "destination_path": { - "description": "Destination virtual_path prefix. Required for `destination_kind=config`, where it must name at least one path segment (`.` and `..` segments are dropped).", - "example": "string", - "type": "string" + "max_pending_events": { + "description": "Queue cap. Defaults to 100; maximum 1000.", + "example": 1, + "type": "integer" }, - "file": { - "description": "Source file id (`fil_...`) for document extraction. Runs synchronously, so the source must be at most 10MB; larger files are rejected.", - "example": "string", + "name": { + "description": "Customer-defined subscription name.", + "example": "Example Name", "type": "string" }, - "max_pages": { - "description": "Crawl cap for `mode=site` — must be at least 1 (defaults to 100; `link` is always 1).", + "retention_seconds": { + "description": "Delivery retention in seconds. Defaults to 86400 (24 hours); between 7200 and 2592000. Applies to future deliveries only.", "example": 1, "type": "integer" }, - "mode": { - "description": "Required with `url`. Document extraction is selected by `file` instead and takes no `mode` (its `kind` is `document`).", + "status": { + "description": "Initial status. Defaults to active.", "enum": [ - "link", - "site" + "active", + "paused" ], - "example": "link", - "type": "string" - }, - "org": { - "description": "Owning organization (`org_...`). Defaults to the viewer's org.", - "example": "string", + "example": "active", "type": "string" }, - "url": { - "description": "Source URL for link/site extraction.", - "example": "https://example.com", - "type": "string" + "visibility_timeout_seconds": { + "description": "Default claim lease in seconds. Defaults to 300.", + "example": 1, + "type": "integer" } }, "required": [ - "destination_kind" + "name", + "event_names" ], "type": "object" } @@ -36067,43 +38948,72 @@ "required": true }, "responses": { - "201": { + "200": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Extraction" + "$ref": "#/components/schemas/EventSubscription" } } }, - "description": "The extraction job. Document extraction returns `201` with `state: \"done\"`; link/site extraction returns `202` with `state: \"running\"`." + "description": "The new volatile subscription." }, - "404": { - "description": "File not found" + "401": { + "description": "Unauthorized" }, "422": { - "description": "Invalid parameters; Unsupported content type" - }, - "502": { - "description": "Service unavailable" + "description": "Invalid parameters; Validation failed" } }, - "summary": "Start an extraction", + "summary": "Create a domain-event subscription", "x-auth": [ "publishable_key", "bearer" ] } }, - "/api/v1/extractions/{extraction}": { + "/api/v1/event_subscriptions/{subscription}": { + "delete": { + "description": "Deletes the subscription and every delivery still in its queue.", + "operationId": "delete_api_v1_event_subscriptions__subscription", + "parameters": [ + { + "description": "Subscription ID (`esub_...`).", + "example": "string", + "in": "path", + "name": "subscription", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "No content" + }, + "401": { + "description": "Unauthorized" + }, + "404": { + "description": "Event subscription not found" + } + }, + "summary": "Delete a domain-event subscription", + "x-auth": [ + "publishable_key", + "bearer" + ] + }, "get": { - "description": "Returns a single extraction job and its current state. Poll this endpoint after\nstarting an async (link/site) extraction until `state` is `done` or `failed`.\n\nAn extraction that exists but is not visible to the current viewer returns `404`\nrather than `403`, so the resource's existence is not revealed.\n", - "operationId": "get_api_v1_extractions__extraction", + "description": "Returns one subscription and its current queue counters.", + "operationId": "get_api_v1_event_subscriptions__subscription", "parameters": [ { - "description": "Extraction ID (`ext_...`).", + "description": "Subscription ID (`esub_...`).", "example": "string", "in": "path", - "name": "extraction", + "name": "subscription", "required": true, "schema": { "type": "string" @@ -36115,131 +39025,579 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Extraction" + "$ref": "#/components/schemas/EventSubscription" } } }, - "description": "The extraction job." + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" }, "404": { - "description": "Extraction not found" + "description": "Event subscription not found" } }, - "summary": "Retrieve an extraction", + "summary": "Get a domain-event subscription", "x-auth": [ "publishable_key", "bearer" ] - } - }, - "/api/v1/files": { - "post": { - "description": "Creates a new file from base64-encoded content and returns the resulting file object,\nincluding a signed download URL. Use this endpoint to store images, documents, or\nother binary assets that can then be referenced by agents, teams, or users.\n\nApp scope is derived from the authenticated viewer's bearer token or publishable key.\nYou may optionally associate the file with an organization, team, user, or agent by\npassing the corresponding ID. If no owner is specified and the viewer is a user, the\nfile is automatically attributed to that user.\n\nPass `share: true` to additionally mint a stable public URL for the file\n(returned as `share_url`), fetchable by anyone without authentication — for\nexample to embed an uploaded image in a GitHub PR body or other external\nmarkdown. The URL does not expire. Sharing is revoked by setting\n`share: false` on `PATCH /api/v1/files/:file` with the same credential\n(or `archastro update file --unshare`); re-enabling sharing\nreactivates previously issued URLs. Only image content types can be\nshared.\n\nReturns `422` when the `data` field is not valid base64, the changeset is\ninvalid, or `share` is requested for a non-image content type.\nReturns `403` when the request lacks the required app scope.\n", - "operationId": "post_api_v1_files", - "parameters": [], + }, + "patch": { + "description": "Updates matching, status, or queue limits for future fanout. Already queued deliveries remain unless a lower cap trims the oldest entries; retention changes apply to future deliveries only.", + "operationId": "patch_api_v1_event_subscriptions__subscription", + "parameters": [ + { + "description": "Subscription ID (`esub_...`).", + "example": "string", + "in": "path", + "name": "subscription", + "required": true, + "schema": { + "type": "string" + } + } + ], "requestBody": { "content": { "application/json": { "schema": { "example": { - "acl": { - "add": [ - { - "actions": [ - "read", - "write" - ], - "principal": "string", - "principal_type": "user" - } + "event_names": [ + "Example Name" + ], + "max_pending_events": 1, + "name": "Example Name", + "retention_seconds": 1, + "status": "active", + "visibility_timeout_seconds": 1 + }, + "properties": { + "event_names": { + "example": [ + "Example Name" ], - "grants": [ - { - "actions": [ - "read", - "write" - ], - "principal": "string", - "principal_type": "user" - } + "items": { + "type": "string" + }, + "type": "array" + }, + "max_pending_events": { + "example": 1, + "type": "integer" + }, + "name": { + "example": "Example Name", + "type": "string" + }, + "retention_seconds": { + "description": "Delivery retention in seconds. Defaults to 86400 (24 hours); between 7200 and 2592000. Applies to future deliveries only.", + "example": 1, + "type": "integer" + }, + "status": { + "enum": [ + "active", + "paused" ], - "remove": [ - { - "principal": "string", - "principal_type": "user" - } - ] + "example": "active", + "type": "string" }, - "agent": "string", - "content_type": "application/json", - "data": "string", - "filename": "string", - "org": "string", - "share": true, - "team": "string", - "user": "string" + "visibility_timeout_seconds": { + "example": 1, + "type": "integer" + } + }, + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EventSubscription" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "404": { + "description": "Event subscription not found" + }, + "422": { + "description": "Invalid parameters; Validation failed" + } + }, + "summary": "Update a domain-event subscription", + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/event_subscriptions/{subscription}/claim": { + "post": { + "description": "Atomically leases the oldest unacknowledged delivery. Returns an empty data array when the queue is empty or its head already has an active lease. Passing max_events opts into batch mode, where leased entries are skipped instead of blocking; wait_seconds bounds a long poll on an empty queue.", + "operationId": "post_api_v1_event_subscriptions__subscription_claim", + "parameters": [ + { + "description": "Subscription ID (`esub_...`).", + "example": "string", + "in": "path", + "name": "subscription", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "example": { + "consumer_id": "string", + "max_events": 1, + "request_id": "string", + "visibility_timeout_seconds": 1, + "wait_seconds": 1 }, "properties": { - "acl": { - "description": "Access control list for the file. Supports explicit `read` and `write` grants to users, teams, organizations, organization roles, agents, or everyone.", - "example": { - "add": [ - { - "actions": [ - "read", - "write" - ], - "principal": "string", - "principal_type": "user" - } - ], - "grants": [ - { - "actions": [ - "read", - "write" - ], - "principal": "string", - "principal_type": "user" - } - ], - "remove": [ - { - "principal": "string", - "principal_type": "user" - } - ] - }, - "properties": { - "add": { - "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", - "example": [ - { - "actions": [ - "read", - "write" - ], - "principal": "string", - "principal_type": "user" - } - ], - "items": { - "description": "A single access-control grant that pairs a principal with the set of actions it is allowed to perform.", - "example": { - "actions": [ - "read", - "write" - ], - "principal": "string", - "principal_type": "user" - }, - "properties": { - "actions": { - "description": "Array of action strings the principal is permitted to perform, e.g. `[\"read\", \"write\"]`. Must contain at least one entry.", - "example": [ - "read", - "write" - ], + "consumer_id": { + "description": "Consumer identity between 1 and 128 bytes, recorded on the lease for attribution.", + "example": "string", + "type": "string" + }, + "max_events": { + "description": "Opts into batch mode: leases up to this many lease-available deliveries (between 1 and 20) in sequence order, skipping leased entries instead of blocking on the head. Omit to keep strict head-of-line semantics.", + "example": 1, + "type": "integer" + }, + "request_id": { + "description": "Idempotency key between 1 and 128 bytes. Use a value unique per claim attempt (e.g. a UUID) — the key is scoped to the subscription, so a reused value takes over whatever leases it last stamped. Retrying a claim with the same request_id while its leases are unexpired returns the same deliveries (regardless of max_events) with fresh receipt handles and refreshed leases.", + "example": "string", + "type": "string" + }, + "visibility_timeout_seconds": { + "description": "Lease duration override between 15 and 3600 seconds.", + "example": 1, + "type": "integer" + }, + "wait_seconds": { + "description": "Long-poll bound between 0 and 20 seconds. When the queue is empty, the request waits up to this long for a delivery before returning an empty data array. 0 (or omitting) returns immediately.", + "example": 1, + "type": "integer" + } + }, + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EventSubscriptionClaim" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "404": { + "description": "Event subscription not found" + }, + "422": { + "description": "Invalid parameters; Validation failed" + } + }, + "summary": "Claim events from a subscription", + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/event_subscriptions/{subscription}/head": { + "get": { + "description": "Returns the oldest unacknowledged delivery without reserving it. This diagnostic read cannot be used as a safe substitute for claim.", + "operationId": "get_api_v1_event_subscriptions__subscription_head", + "parameters": [ + { + "description": "Subscription ID (`esub_...`).", + "example": "string", + "in": "path", + "name": "subscription", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EventSubscriptionHead" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "404": { + "description": "Event subscription not found" + } + }, + "summary": "Peek at the head of a subscription queue", + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/event_subscriptions/{subscription}/queue": { + "get": { + "description": "Returns a non-reserving, oldest-first view of unacknowledged deliveries, including the queue's loss indicators (queue_epoch, dropped_events_total, dropped_through_position). Use claim to obtain a receipt handle before acknowledging.", + "operationId": "get_api_v1_event_subscriptions__subscription_queue", + "parameters": [ + { + "description": "Subscription ID (`esub_...`).", + "example": "string", + "in": "path", + "name": "subscription", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Maximum entries to return, from 1 through 100.", + "example": 1, + "in": "query", + "name": "limit", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "description": "Opaque cursor for the preceding page.", + "example": "string", + "in": "query", + "name": "before_cursor", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Opaque cursor for the following page.", + "example": "string", + "in": "query", + "name": "after_cursor", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EventSubscriptionQueue" + } + } + }, + "description": "Successful response" + }, + "400": { + "description": "Invalid cursor" + }, + "401": { + "description": "Unauthorized" + }, + "404": { + "description": "Event subscription not found" + } + }, + "summary": "Read a subscription queue", + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/extractions": { + "post": { + "description": "Records a text-extraction job for a document (`file`) or a URL (`url` + `mode`).\nThe job is owner-scoped and tagged with the caller-supplied `destination`\nnamespace, **without** committing knowledge to an agent (no embeddings, no\nagent attach).\n\nExactly one of `file` or (`url` + `mode`) is required.\n\nDocument extraction (`file`) runs synchronously: the response already\nreflects the final state (`done` with its output, or an error if extraction\ncouldn't complete), status `201`. URL extraction (`url` + `mode`) submits an\nasync crawl and returns immediately with state `running`, status `202` —\npoll `GET /extractions/:extraction` for its terminal state.\n", + "operationId": "post_api_v1_extractions", + "parameters": [], + "requestBody": { + "content": { + "application/json": { + "schema": { + "example": { + "agent": "string", + "destination_kind": "config", + "destination_path": "string", + "file": "string", + "max_pages": 1, + "mode": "link", + "org": "string", + "url": "https://example.com" + }, + "properties": { + "agent": { + "description": "Owning agent (`agt_...`) — scopes the extraction and its outputs.", + "example": "string", + "type": "string" + }, + "destination_kind": { + "description": "Where outputs are written.", + "enum": [ + "config", + "storage" + ], + "example": "config", + "type": "string" + }, + "destination_path": { + "description": "Destination virtual_path prefix. Required for `destination_kind=config`, where it must name at least one path segment (`.` and `..` segments are dropped).", + "example": "string", + "type": "string" + }, + "file": { + "description": "Source file id (`fil_...`) for document extraction. Runs synchronously, so the source must be at most 10MB; larger files are rejected.", + "example": "string", + "type": "string" + }, + "max_pages": { + "description": "Crawl cap for `mode=site` — must be at least 1 (defaults to 100; `link` is always 1).", + "example": 1, + "type": "integer" + }, + "mode": { + "description": "Required with `url`. Document extraction is selected by `file` instead and takes no `mode` (its `kind` is `document`).", + "enum": [ + "link", + "site" + ], + "example": "link", + "type": "string" + }, + "org": { + "description": "Owning organization (`org_...`). Defaults to the viewer's org.", + "example": "string", + "type": "string" + }, + "url": { + "description": "Source URL for link/site extraction.", + "example": "https://example.com", + "type": "string" + } + }, + "required": [ + "destination_kind" + ], + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "201": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Extraction" + } + } + }, + "description": "The extraction job. Document extraction returns `201` with `state: \"done\"`; link/site extraction returns `202` with `state: \"running\"`." + }, + "404": { + "description": "File not found" + }, + "422": { + "description": "Invalid parameters; Unsupported content type" + }, + "502": { + "description": "Service unavailable" + } + }, + "summary": "Start an extraction", + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/extractions/{extraction}": { + "get": { + "description": "Returns a single extraction job and its current state. Poll this endpoint after\nstarting an async (link/site) extraction until `state` is `done` or `failed`.\n\nAn extraction that exists but is not visible to the current viewer returns `404`\nrather than `403`, so the resource's existence is not revealed.\n", + "operationId": "get_api_v1_extractions__extraction", + "parameters": [ + { + "description": "Extraction ID (`ext_...`).", + "example": "string", + "in": "path", + "name": "extraction", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Extraction" + } + } + }, + "description": "The extraction job." + }, + "404": { + "description": "Extraction not found" + } + }, + "summary": "Retrieve an extraction", + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/files": { + "post": { + "description": "Creates a new file from base64-encoded content and returns the resulting file object,\nincluding a signed download URL. Use this endpoint to store images, documents, or\nother binary assets that can then be referenced by agents, teams, or users.\n\nApp scope is derived from the authenticated viewer's bearer token or publishable key.\nYou may optionally associate the file with an organization, team, user, or agent by\npassing the corresponding ID. If no owner is specified and the viewer is a user, the\nfile is automatically attributed to that user.\n\nPass `share: true` to additionally mint a stable public URL for the file\n(returned as `share_url`), fetchable by anyone without authentication — for\nexample to embed an uploaded image in a GitHub PR body or other external\nmarkdown. The URL does not expire. Sharing is revoked by setting\n`share: false` on `PATCH /api/v1/files/:file` with the same credential\n(or `archastro update file --unshare`); re-enabling sharing\nreactivates previously issued URLs. Only image content types can be\nshared.\n\nReturns `422` when the `data` field is not valid base64, the changeset is\ninvalid, or `share` is requested for a non-image content type.\nReturns `403` when the request lacks the required app scope.\n", + "operationId": "post_api_v1_files", + "parameters": [], + "requestBody": { + "content": { + "application/json": { + "schema": { + "example": { + "acl": { + "add": [ + { + "actions": [ + "read", + "write" + ], + "principal": "string", + "principal_type": "user" + } + ], + "grants": [ + { + "actions": [ + "read", + "write" + ], + "principal": "string", + "principal_type": "user" + } + ], + "remove": [ + { + "principal": "string", + "principal_type": "user" + } + ] + }, + "agent": "string", + "content_type": "application/json", + "data": "string", + "filename": "string", + "org": "string", + "share": true, + "team": "string", + "user": "string" + }, + "properties": { + "acl": { + "description": "Access control list for the file. Supports explicit `read` and `write` grants to users, teams, organizations, organization roles, agents, or everyone.", + "example": { + "add": [ + { + "actions": [ + "read", + "write" + ], + "principal": "string", + "principal_type": "user" + } + ], + "grants": [ + { + "actions": [ + "read", + "write" + ], + "principal": "string", + "principal_type": "user" + } + ], + "remove": [ + { + "principal": "string", + "principal_type": "user" + } + ] + }, + "properties": { + "add": { + "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", + "example": [ + { + "actions": [ + "read", + "write" + ], + "principal": "string", + "principal_type": "user" + } + ], + "items": { + "description": "A single access-control grant that pairs a principal with the set of actions it is allowed to perform.", + "example": { + "actions": [ + "read", + "write" + ], + "principal": "string", + "principal_type": "user" + }, + "properties": { + "actions": { + "description": "Array of action strings the principal is permitted to perform, e.g. `[\"read\", \"write\"]`. Must contain at least one entry.", + "example": [ + "read", + "write" + ], "items": { "type": "string" }, @@ -37803,6 +41161,9 @@ }, "422": { "description": "Invalid parameters; Validation failed" + }, + "502": { + "description": "Service unavailable" } }, "summary": "Create a knowledge source", @@ -37992,7 +41353,10 @@ "description": "Knowledge source not found" }, "422": { - "description": "Validation failed" + "description": "Invalid parameters; Validation failed" + }, + "502": { + "description": "Service unavailable" } }, "summary": "Update a knowledge source", @@ -40214,6 +43578,9 @@ "401": { "description": "Unauthorized" }, + "402": { + "description": "Payment required" + }, "403": { "description": "Forbidden; Admin role required for this operation; The Slack integration referenced by this binding is not visible to the caller" }, @@ -40227,7 +43594,7 @@ "description": "Internal server error" }, "502": { - "description": "Provider returned an error" + "description": "Provider returned an error; Service unavailable" } }, "summary": "Start adding a customer over Slack Connect", @@ -40366,6 +43733,109 @@ ] } }, + "/api/v1/slack_channel_bindings/{channel}/delivery_outcomes": { + "get": { + "description": "Returns what happened to each agent message this platform sent to a Slack\nchannel, newest attempt first.\n\nA message that never appears in a Slack channel has several possible causes\nthat look identical from the channel itself: a content guard withheld it, the\ncross-org judge refused it, Slack rejected the call, or nobody asked anything.\nThis endpoint tells them apart. Use it to confirm a reply was delivered, or to\nfind out why one never arrived, without reading the channel's mirrored\nconversation.\n\nOutcomes cover **outbound agent messages only**. They carry no message\ncontent, no author, and nothing about inbound messages. Access follows the\nchannel's binding — the organization and app the channel is bound to — and\nneeds no membership in the mirrored thread.\n\nPaginated with opaque cursors, newest first. When `has_more` is true, pass the\nresponse's `before_cursor` back as `before_cursor` to continue into older\nhistory. `since` and `outcome` narrow the result set; they are filters, not\npaging controls.\n", + "operationId": "get_api_v1_slack_channel_bindings__channel_delivery_outcomes", + "parameters": [ + { + "description": "Slack channel ID to read delivery outcomes for (e.g. `C01234ABCDE`).", + "example": "string", + "in": "path", + "name": "channel", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Only return attempts at or after this ISO 8601 timestamp (e.g. `2026-08-11T00:00:00Z`). Omit to return the most recent attempts regardless of age.", + "example": "string", + "in": "query", + "name": "since", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Return only attempts with this outcome. Omit to return every outcome. Use `floored` and `judge_refused` to see only what was withheld.", + "example": "delivered", + "in": "query", + "name": "outcome", + "required": false, + "schema": { + "enum": [ + "delivered", + "floored", + "judge_refused", + "failed" + ], + "type": "string" + } + }, + { + "description": "Maximum number of outcomes to return. Defaults to 50; maximum is 200.", + "example": 1, + "in": "query", + "name": "limit", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "description": "Opaque cursor from a previous response; returns outcomes older than it. Cursors are not parseable and are only valid against this endpoint.", + "example": "string", + "in": "query", + "name": "before_cursor", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Opaque cursor from a previous response; returns outcomes newer than it. Suited to a UI loading newer entries. To poll for everything recorded since a point in time, prefer `since` with a little overlap and de-duplicate on `id` — `after_cursor` can miss an attempt recorded in the same millisecond as the cursor's own row.", + "example": "string", + "in": "query", + "name": "after_cursor", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SlackDeliveryOutcomeListResponse" + } + } + }, + "description": "Delivery outcomes for the requested channel, newest first." + }, + "400": { + "description": "Bad request" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "422": { + "description": "Invalid parameters" + } + }, + "summary": "List delivery outcomes for a Slack channel", + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, "/api/v1/slack_channel_bindings/{channel}/deposit_thread": { "post": { "description": "Sets the binding's deposit target — the internal staging thread the\ndeposit pipe copies this channel's mirror content into. Pass a `null`\n`thread_id` to turn the pipe off.\n\nThe target is validated server-side: it must exist, belong to the\nbinding's app and org, and never be a Slack mirror thread. Customer\nbindings (bound `team_id`) additionally require a team-owned private\nthread with no participant list, so the staging read ACL stays governed\nby the channel-membership projection. Re-pointing or clearing an\nexisting target purges the old thread's deposit entries.\n", @@ -42072,6 +45542,56 @@ "summary": "Retrieve a Solution README or asset" } }, + "/api/v1/solutions/{solution}/reconcile_product_knowledge": { + "post": { + "description": "Recomputes every stamped customer's knowledge-search source allowlist\nfrom the template-resolved customer refs plus the install's current marked\nproduct-knowledge sources. Safe to retry; partial failures are returned by\ncustomer key rather than hidden behind an aggregate success.\n", + "operationId": "post_api_v1_solutions__solution_reconcile_product_knowledge", + "parameters": [ + { + "description": "Installed Customer Management Solution config (`cfg_...`) to reconcile.", + "example": "string", + "in": "path", + "name": "solution", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProductKnowledgeReconcileResponse" + } + } + }, + "description": "Per-customer convergence result for this installed solution." + }, + "400": { + "description": "Bad request" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Solution not found" + }, + "502": { + "description": "Service unavailable" + } + }, + "summary": "Reconcile Customer Management product knowledge", + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, "/api/v1/solutions/{solution}/upgrade": { "post": { "description": "Applies an incoming bundle to an already-installed Solution in a single atomic\ntransaction, bringing its configs in line with the new bundle. Config IDs are\npreserved across the upgrade. Configs that existed in the old bundle but are\nabsent from the new one are orphaned (top-level) or hard-deleted (child rows).\n\nTwo mutually exclusive source modes: pass `target_solution` to pull the\nincoming bundle from an existing Solution by ID or `lookup_key`, or pass\n`solution_bundle` to supply a complete inline bundle directly. Exactly one\nmust be present.\n\nWhen `dry_run` is `true` the full diff is computed and returned but no\nchanges are written. Pass the dry-run response's `review_fingerprint` as\n`expected_review_fingerprint` when applying to guard against the bundle\nchanging between review and apply.\n", @@ -42933,6 +46453,7 @@ "agent": "string", "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "lease_id": "string", "lease_session_id": "string", "links": {}, @@ -42945,6 +46466,9 @@ "owner_user": "string", "parent": "string", "priority": 1, + "source_id": "string", + "source_scope": "string", + "source_type": "string", "status": "string", "tags": [ "string" @@ -42969,6 +46493,11 @@ "format": "date-time", "type": "string" }, + "epic": { + "description": "Replacement grouping label. Pass null to clear it.", + "example": "string", + "type": "string" + }, "lease_id": { "description": "Current caller-held lease UUID. Must be paired with `lease_session_id`.", "example": "string", @@ -43021,6 +46550,21 @@ "example": 1, "type": "integer" }, + "source_id": { + "description": "Replacement source object identity. Must be supplied with the other source fields.", + "example": "string", + "type": "string" + }, + "source_scope": { + "description": "Replacement source container. Pass together with `source_type` and `source_id`, or pass all three as null to clear the source.", + "example": "string", + "type": "string" + }, + "source_type": { + "description": "Replacement source object kind. Must be supplied with the other source fields.", + "example": "string", + "type": "string" + }, "status": { "description": "Updated status: `open`, `in_progress`, or `done`.", "example": "string", @@ -43374,6 +46918,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -43403,6 +46948,9 @@ "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "priority": 2, "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", "status": "open", "subtasks_count": 1, "tags": [ @@ -43456,6 +47004,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -43485,6 +47034,9 @@ "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "priority": 2, "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", "status": "open", "subtasks_count": 1, "tags": [ @@ -43527,6 +47079,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -43556,6 +47109,9 @@ "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "priority": 2, "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", "status": "open", "subtasks_count": 1, "tags": [ @@ -43570,6 +47126,7 @@ "agent": { "description": "ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "blocked_by_count": { @@ -43581,6 +47138,7 @@ "description": "When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", "example": "2024-01-01T00:00:00Z", "format": "date-time", + "nullable": true, "type": "string" }, "comments_count": { @@ -43610,193 +47168,24 @@ "width": 800 } }, - "properties": { - "alias": { - "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", - "example": "alice", - "type": "string" - }, - "id": { - "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", - "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", - "type": "string" - }, - "name": { - "description": "Display name of the actor shown in the UI. `null` if no name is set.", - "example": "Example Name", - "type": "string" - }, - "profile_picture": { - "description": "Profile picture for the actor. `null` if the actor has no profile picture.", - "example": { - "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", - "height": 600, - "media": "med_0aBcDeFgHiJkLmNoPqRsTu", - "mime_type": "application/json", - "refresh_url": "https://example.com", - "url": "https://example.com", - "width": 800 - }, - "properties": { - "file": { - "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", - "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "height": { - "description": "Height of the image in pixels. `null` if not known.", - "example": 600, - "type": "integer" - }, - "media": { - "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", - "example": "med_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "mime_type": { - "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", - "example": "application/json", - "type": "string" - }, - "refresh_url": { - "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.", - "example": "https://example.com", - "type": "string" - }, - "url": { - "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.", - "example": "https://example.com", - "type": "string" - }, - "width": { - "description": "Width of the image in pixels. `null` if not known.", - "example": 800, - "type": "integer" - } - }, - "type": "object" - } - }, - "type": "object" - }, - "created_by_agent": { - "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.", - "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "created_by_user": { - "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.", - "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "current_lease": { - "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.", - "example": { - "expires_at": "2024-01-01T00:00:00Z", - "harness": "string", - "session_name": "Example Name" - }, "nullable": true, - "properties": { - "expires_at": { - "description": "Server-calculated lease expiry in ISO 8601 format.", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", - "type": "string" - }, - "harness": { - "description": "Bounded harness identifier for the coding session.", - "example": "string", - "type": "string" - }, - "session_name": { - "description": "Display name supplied by the coding session that holds the lease.", - "example": "Example Name", - "type": "string" - } - }, - "required": [ - "session_name", - "harness", - "expires_at" - ], - "type": "object" - }, - "description": { - "description": "Long-form description or notes for the task. `null` if no description has been provided.", - "example": "An example description.", - "type": "string" - }, - "due_date": { - "description": "Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", - "type": "string" - }, - "id": { - "description": "Task ID (`tsk_...`).", - "example": "tsk_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "is_blocked": { - "description": "`true` while at least one blocking task is not yet done. Informational only — a blocked task can still change status — and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on list/show reads; create/update responses report `false` until the next read.", - "example": true, - "type": "boolean" - }, - "links": { - "description": "Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.", - "example": { - "key": "value" - }, - "type": "object" - }, - "metadata": { - "description": "Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.", - "example": { - "key": "value" - }, - "type": "object" - }, - "name": { - "description": "Human-readable title of the task.", - "example": "Example Name", - "type": "string" - }, - "org": { - "description": "ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", - "example": "org_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "owner_actor": { - "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).", - "example": { - "alias": "alice", - "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", - "name": "Example Name", - "profile_picture": { - "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", - "height": 600, - "media": "med_0aBcDeFgHiJkLmNoPqRsTu", - "mime_type": "application/json", - "refresh_url": "https://example.com", - "url": "https://example.com", - "width": 800 - } - }, "properties": { "alias": { "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", "example": "alice", + "nullable": true, "type": "string" }, "id": { "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "nullable": true, "type": "string" }, "name": { "description": "Display name of the actor shown in the UI. `null` if no name is set.", "example": "Example Name", + "nullable": true, "type": "string" }, "profile_picture": { @@ -43810,40 +47199,244 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, + "type": "integer" + } + }, + "type": "object" + } + }, + "type": "object" + }, + "created_by_agent": { + "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.", + "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_user": { + "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.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "current_lease": { + "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.", + "example": { + "expires_at": "2024-01-01T00:00:00Z", + "harness": "string", + "session_name": "Example Name" + }, + "nullable": true, + "properties": { + "expires_at": { + "description": "Server-calculated lease expiry in ISO 8601 format.", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "type": "string" + }, + "harness": { + "description": "Bounded harness identifier for the coding session.", + "example": "string", + "type": "string" + }, + "session_name": { + "description": "Display name supplied by the coding session that holds the lease.", + "example": "Example Name", + "type": "string" + } + }, + "required": [ + "session_name", + "harness", + "expires_at" + ], + "type": "object" + }, + "description": { + "description": "Long-form description or notes for the task. `null` if no description has been provided.", + "example": "An example description.", + "nullable": true, + "type": "string" + }, + "due_date": { + "description": "Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "nullable": true, + "type": "string" + }, + "epic": { + "description": "Free-form grouping label. `null` when the task is not in an epic.", + "example": "string", + "nullable": true, + "type": "string" + }, + "id": { + "description": "Task ID (`tsk_...`).", + "example": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "is_blocked": { + "description": "`true` while at least one blocking task is not yet done. Informational only — a blocked task can still change status — and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on list/show reads; create/update responses report `false` until the next read.", + "example": true, + "type": "boolean" + }, + "links": { + "description": "Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.", + "example": { + "key": "value" + }, + "type": "object" + }, + "metadata": { + "description": "Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.", + "example": { + "key": "value" + }, + "type": "object" + }, + "name": { + "description": "Human-readable title of the task.", + "example": "Example Name", + "type": "string" + }, + "org": { + "description": "ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "owner_actor": { + "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).", + "example": { + "alias": "alice", + "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "name": "Example Name", + "profile_picture": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + } + }, + "nullable": true, + "properties": { + "alias": { + "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", + "example": "alice", + "nullable": true, + "type": "string" + }, + "id": { + "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", + "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "nullable": true, + "type": "string" + }, + "name": { + "description": "Display name of the actor shown in the UI. `null` if no name is set.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "profile_picture": { + "description": "Profile picture for the actor. `null` if the actor has no profile picture.", + "example": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + }, + "nullable": true, + "properties": { + "file": { + "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", + "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "height": { + "description": "Height of the image in pixels. `null` if not known.", + "example": 600, + "nullable": true, + "type": "integer" + }, + "media": { + "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", + "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "mime_type": { + "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", + "example": "application/json", + "nullable": true, + "type": "string" + }, + "refresh_url": { + "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.", + "example": "https://example.com", + "nullable": true, + "type": "string" + }, + "url": { + "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.", + "example": "https://example.com", + "nullable": true, + "type": "string" + }, + "width": { + "description": "Width of the image in pixels. `null` if not known.", + "example": 800, + "nullable": true, "type": "integer" } }, @@ -43855,16 +47448,19 @@ "owner_agent": { "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.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "owner_user": { "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.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "parent": { "description": "ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks. Subtasks nest exactly one level.", "example": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "priority": { @@ -43875,6 +47471,25 @@ "sandbox": { "description": "ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "source_id": { + "description": "Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", + "example": "string", + "nullable": true, + "type": "string" + }, + "source_scope": { + "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`.", + "example": "string", + "nullable": true, + "type": "string" + }, + "source_type": { + "description": "Kind of source object (for example `repository`). `null` when the task has no source.", + "example": "string", + "nullable": true, "type": "string" }, "status": { @@ -43900,11 +47515,13 @@ "team": { "description": "ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "thread": { "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.", "example": "thr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "updated_at": { @@ -43916,6 +47533,7 @@ "user": { "description": "ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" } }, @@ -44211,6 +47829,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -44240,6 +47859,9 @@ "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "priority": 2, "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", "status": "open", "subtasks_count": 1, "tags": [ @@ -44293,6 +47915,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -44322,6 +47945,9 @@ "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "priority": 2, "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", "status": "open", "subtasks_count": 1, "tags": [ @@ -44364,6 +47990,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -44393,6 +48020,9 @@ "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "priority": 2, "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", "status": "open", "subtasks_count": 1, "tags": [ @@ -44407,6 +48037,7 @@ "agent": { "description": "ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "blocked_by_count": { @@ -44418,6 +48049,7 @@ "description": "When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", "example": "2024-01-01T00:00:00Z", "format": "date-time", + "nullable": true, "type": "string" }, "comments_count": { @@ -44447,20 +48079,24 @@ "width": 800 } }, + "nullable": true, "properties": { "alias": { "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", "example": "alice", + "nullable": true, "type": "string" }, "id": { "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "nullable": true, "type": "string" }, "name": { "description": "Display name of the actor shown in the UI. `null` if no name is set.", "example": "Example Name", + "nullable": true, "type": "string" }, "profile_picture": { @@ -44474,40 +48110,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -44519,11 +48163,13 @@ "created_by_agent": { "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.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "created_by_user": { "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.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "current_lease": { @@ -44562,12 +48208,20 @@ "description": { "description": "Long-form description or notes for the task. `null` if no description has been provided.", "example": "An example description.", + "nullable": true, "type": "string" }, "due_date": { "description": "Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", "example": "2024-01-01T00:00:00Z", "format": "date-time", + "nullable": true, + "type": "string" + }, + "epic": { + "description": "Free-form grouping label. `null` when the task is not in an epic.", + "example": "string", + "nullable": true, "type": "string" }, "id": { @@ -44602,6 +48256,7 @@ "org": { "description": "ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "owner_actor": { @@ -44620,20 +48275,24 @@ "width": 800 } }, + "nullable": true, "properties": { "alias": { "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", "example": "alice", + "nullable": true, "type": "string" }, "id": { "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "nullable": true, "type": "string" }, "name": { "description": "Display name of the actor shown in the UI. `null` if no name is set.", "example": "Example Name", + "nullable": true, "type": "string" }, "profile_picture": { @@ -44647,40 +48306,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -44692,16 +48359,19 @@ "owner_agent": { "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.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "owner_user": { "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.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "parent": { "description": "ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks. Subtasks nest exactly one level.", "example": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "priority": { @@ -44712,6 +48382,25 @@ "sandbox": { "description": "ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "source_id": { + "description": "Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", + "example": "string", + "nullable": true, + "type": "string" + }, + "source_scope": { + "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`.", + "example": "string", + "nullable": true, + "type": "string" + }, + "source_type": { + "description": "Kind of source object (for example `repository`). `null` when the task has no source.", + "example": "string", + "nullable": true, "type": "string" }, "status": { @@ -44737,11 +48426,13 @@ "team": { "description": "ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "thread": { "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.", "example": "thr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "updated_at": { @@ -44753,6 +48444,7 @@ "user": { "description": "ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" } }, @@ -44999,16 +48691,19 @@ "alias": { "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", "example": "alice", + "nullable": true, "type": "string" }, "id": { "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "nullable": true, "type": "string" }, "name": { "description": "Display name of the actor shown in the UI. `null` if no name is set.", "example": "Example Name", + "nullable": true, "type": "string" }, "profile_picture": { @@ -45022,40 +48717,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -45479,6 +49182,7 @@ "harness": "string", "lease_duration_seconds": 1, "lease_id": "string", + "require_ready": true, "session_id": "string", "session_name": "Example Name" }, @@ -45499,6 +49203,12 @@ "example": "string", "type": "string" }, + "require_ready": { + "default": false, + "description": "Conservatively reject the claim when the current task projection has unfinished blockers.", + "example": true, + "type": "boolean" + }, "session_id": { "description": "Caller-generated coding-session UUID.", "example": "string", @@ -45643,6 +49353,123 @@ ] } }, + "/api/v1/tasks/{task}/links": { + "delete": { + "operationId": "delete_api_v1_tasks__task_links", + "parameters": [ + { + "description": "Task ID (`tsk_...`).", + "example": "string", + "in": "path", + "name": "task", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "HTTP 204 on success." + }, + "401": { + "description": "Unauthorized" + }, + "404": { + "description": "Task not found; Resource not found" + }, + "502": { + "description": "Service unavailable" + } + }, + "summary": "Remove an external link from a task", + "x-auth": [ + "publishable_key", + "bearer" + ] + }, + "post": { + "operationId": "post_api_v1_tasks__task_links", + "parameters": [ + { + "description": "Task ID (`tsk_...`).", + "example": "string", + "in": "path", + "name": "task", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "example": { + "external_scope": "string", + "object_id": "string", + "object_type": "string" + }, + "properties": { + "external_scope": { + "description": "External container ID.", + "example": "string", + "type": "string" + }, + "object_id": { + "description": "External object ID.", + "example": "string", + "type": "string" + }, + "object_type": { + "description": "External object type.", + "example": "string", + "type": "string" + } + }, + "required": [ + "external_scope", + "object_type", + "object_id" + ], + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "type": "object" + } + } + }, + "description": "The created external link." + }, + "401": { + "description": "Unauthorized" + }, + "404": { + "description": "Task not found" + }, + "422": { + "description": "Invalid parameters" + }, + "502": { + "description": "Service unavailable" + } + }, + "summary": "Add an external link to a task", + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, "/api/v1/tasks/{task}/subtasks": { "get": { "description": "Returns a bounded page of the specified task's subtasks (tasks whose\n`parent` is this task), newest first. Subtasks nest exactly one level, so\nentries never have subtasks of their own. Privileged callers explicitly\nprovide the owning `team`, `user`, or `agent` and `org`.\n", @@ -45758,6 +49585,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -45787,6 +49615,9 @@ "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "priority": 2, "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", "status": "open", "subtasks_count": 1, "tags": [ @@ -45840,6 +49671,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -45869,6 +49701,9 @@ "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "priority": 2, "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", "status": "open", "subtasks_count": 1, "tags": [ @@ -45911,6 +49746,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -45940,6 +49776,9 @@ "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "priority": 2, "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", "status": "open", "subtasks_count": 1, "tags": [ @@ -45954,6 +49793,7 @@ "agent": { "description": "ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "blocked_by_count": { @@ -45965,6 +49805,7 @@ "description": "When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", "example": "2024-01-01T00:00:00Z", "format": "date-time", + "nullable": true, "type": "string" }, "comments_count": { @@ -45994,20 +49835,24 @@ "width": 800 } }, + "nullable": true, "properties": { "alias": { "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", "example": "alice", + "nullable": true, "type": "string" }, "id": { "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "nullable": true, "type": "string" }, "name": { "description": "Display name of the actor shown in the UI. `null` if no name is set.", "example": "Example Name", + "nullable": true, "type": "string" }, "profile_picture": { @@ -46021,40 +49866,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -46066,11 +49919,13 @@ "created_by_agent": { "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.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "created_by_user": { "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.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "current_lease": { @@ -46109,12 +49964,20 @@ "description": { "description": "Long-form description or notes for the task. `null` if no description has been provided.", "example": "An example description.", + "nullable": true, "type": "string" }, "due_date": { "description": "Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", "example": "2024-01-01T00:00:00Z", "format": "date-time", + "nullable": true, + "type": "string" + }, + "epic": { + "description": "Free-form grouping label. `null` when the task is not in an epic.", + "example": "string", + "nullable": true, "type": "string" }, "id": { @@ -46149,6 +50012,7 @@ "org": { "description": "ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "owner_actor": { @@ -46167,20 +50031,24 @@ "width": 800 } }, + "nullable": true, "properties": { "alias": { "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", "example": "alice", + "nullable": true, "type": "string" }, "id": { "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "nullable": true, "type": "string" }, "name": { "description": "Display name of the actor shown in the UI. `null` if no name is set.", "example": "Example Name", + "nullable": true, "type": "string" }, "profile_picture": { @@ -46194,40 +50062,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -46239,16 +50115,19 @@ "owner_agent": { "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.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "owner_user": { "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.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "parent": { "description": "ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks. Subtasks nest exactly one level.", "example": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "priority": { @@ -46259,6 +50138,25 @@ "sandbox": { "description": "ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "source_id": { + "description": "Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", + "example": "string", + "nullable": true, + "type": "string" + }, + "source_scope": { + "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`.", + "example": "string", + "nullable": true, + "type": "string" + }, + "source_type": { + "description": "Kind of source object (for example `repository`). `null` when the task has no source.", + "example": "string", + "nullable": true, "type": "string" }, "status": { @@ -46284,11 +50182,13 @@ "team": { "description": "ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "thread": { "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.", "example": "thr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "updated_at": { @@ -46300,6 +50200,7 @@ "user": { "description": "ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" } }, @@ -46465,6 +50366,9 @@ "401": { "description": "Unauthorized" }, + "403": { + "description": "Forbidden" + }, "404": { "description": "Team or member not found" } @@ -46798,6 +50702,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -46949,6 +50854,7 @@ "badges": { "description": "Aggregated badge counts for the team, keyed by category. `null` when badge data is not loaded.", "example": {}, + "nullable": true, "type": "object" }, "created_at": { @@ -46960,6 +50866,7 @@ "description": { "description": "Human-readable description of the team's purpose. `null` if not set.", "example": "An example description.", + "nullable": true, "type": "string" }, "id": { @@ -46970,6 +50877,7 @@ "membership_status": { "description": "The authenticated viewer's role on this team. One of `\"owner\"`, `\"admin\"`, or `\"member\"`. `null` if the viewer is not a member.", "example": "member", + "nullable": true, "type": "string" }, "metadata": { @@ -46987,16 +50895,19 @@ "org": { "description": "ID of the organization this team belongs to (`org_...`). `null` if the team is not org-scoped.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the developer sandbox this team is scoped to (`dsb_...`). `null` outside sandbox contexts.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "slug": { "description": "URL-safe slug for the team, derived from the team name. `null` if not set.", "example": "example-slug", + "nullable": true, "type": "string" }, "updated_at": { @@ -48004,36 +51915,43 @@ "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -49158,6 +53076,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -49168,6 +53091,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -49384,6 +53308,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -49394,6 +53323,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -49607,6 +53537,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -49617,6 +53552,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -49805,6 +53741,7 @@ "updated_at": "2024-01-01T00:00:00Z", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" }, + "nullable": true, "properties": { "acl": { "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.", @@ -49836,6 +53773,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -49986,23 +53924,25 @@ }, "created_at": { "description": "When the agent was created (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "default_model": { "description": "Default LLM model identifier used by this agent when no model is specified at runtime (e.g. `\"claude-3-7-sonnet-latest\"`).", "example": "claude-3-7-sonnet-latest", + "nullable": true, "type": "string" }, "description": { "description": "Human-readable description of what the agent does. `null` if not set.", "example": "An example description.", + "nullable": true, "type": "string" }, "email": { "description": "Email address provisioned for this agent. `null` if email delivery is not configured.", "example": "user@example.com", + "nullable": true, "type": "string" }, "id": { @@ -50013,16 +53953,19 @@ "identity": { "description": "System-level identity prompt that shapes the agent's persona and behavior.", "example": "You are a helpful assistant that answers questions about ArchAstro products.", + "nullable": true, "type": "string" }, "last_applied_template_config": { "description": "ID of the AgentTemplate config (`cfg_...`) this agent was last provisioned or updated from. `null` for manually created agents.", "example": "cfg_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "lookup_key": { "description": "Stable, user-defined identifier for this agent within the application. Unique per app.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -50040,26 +53983,31 @@ "org": { "description": "ID of the organization this agent belongs to (`org_...`). `null` if the agent is not org-scoped.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_name": { "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.", "example": "Example Name", + "nullable": true, "type": "string" }, "originator": { "description": "Free-form label identifying the source or author that created this agent (e.g. a username or pipeline name).", "example": "deploy-pipeline", + "nullable": true, "type": "string" }, "phone_number": { "description": "Phone number provisioned for this agent. `null` if SMS is not configured.", "example": "+15555550123", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the sandbox environment this agent is scoped to (`dsb_...`). `null` in production deployments.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "source_solution": { @@ -50193,6 +54141,7 @@ "virtual_path": "string" } }, + "nullable": true, "properties": { "current_solution": { "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.", @@ -50267,13 +54216,13 @@ }, "created_at": { "description": "When the Solution config was first imported (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "events": { @@ -50289,6 +54238,7 @@ "image_url": { "description": "Absolute URL of the Solution's cover image — the bundled asset the body's `image:` field names. A stable, non-expiring capability URL (like `org_logo.url`), safe to hold in caches and OpenGraph tags; it 404s if the Solution stops declaring a cover. `null` when the Solution has no cover image, and always `null` for org-scoped rows — the permanent URL is minted for system-scope (catalog) Solutions only.", "example": "https://example.com", + "nullable": true, "type": "string" }, "kind": { @@ -50299,16 +54249,19 @@ "latest_solution": { "description": "When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "latest_version": { "description": "When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", "example": "1.0.0", + "nullable": true, "type": "string" }, "lookup_key": { "description": "The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -50321,11 +54274,13 @@ "name": { "description": "Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "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.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_logo": { @@ -50339,40 +54294,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -50381,11 +54344,13 @@ "org_name": { "description": "Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_slug": { "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.", "example": "example-slug", + "nullable": true, "type": "string" }, "owners": { @@ -50401,6 +54366,7 @@ "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "screenshot_urls": { @@ -50416,11 +54382,13 @@ "solution_id": { "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.", "example": "01234567-89ab-cdef-0123-456789abcdef", + "nullable": true, "type": "string" }, "solution_version": { "description": "Semver string declared in the Solution body (e.g. `\"1.2.0\"`). `null` when the body does not declare a version.", "example": "1.2.0", + "nullable": true, "type": "string" }, "tag_keys": { @@ -50436,6 +54404,7 @@ "template_kind": { "description": "Wrapped template kind — `\"AgentTemplate\"`, `\"AutomationTemplate\"`, `\"AgentRoutineTemplate\"`, `\"AgentToolTemplate\"`, `\"AgentComputerTemplate\"`, or `\"SolutionTemplateRef\"` for ref-mode bundles.", "example": "AgentTemplate", + "nullable": true, "type": "string" }, "templates": { @@ -50468,6 +54437,7 @@ "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "details": { @@ -50475,6 +54445,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -50499,12 +54470,13 @@ }, "properties": { "automation_type": { - "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`).", + "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", "example": "string", + "nullable": true, "type": "string" }, "invoke_contract": { - "description": "Schema-driven payload and participant inputs for an invoked automation. Used by installation clients to collect locked prefills before provisioning.", + "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.", "example": { "input_schema": {}, "participants": [ @@ -50520,10 +54492,12 @@ "payload": {} } }, + "nullable": true, "properties": { "input_schema": { "description": "JSON Schema validated against the whole invoke payload, from the automation's `input_schema_config`. `null` when none is configured.", "example": {}, + "nullable": true, "type": "object" }, "participants": { @@ -50544,10 +54518,12 @@ "required": true, "type": "agent_user" }, + "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", "example": "An example description.", + "nullable": true, "type": "string" }, "name": { @@ -50573,6 +54549,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -50621,11 +54598,13 @@ "display_name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "id": { "description": "Template config ID (`cfg_...`). `null` for inline-only templates.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "kind": { @@ -50636,21 +54615,25 @@ "lookup_key": { "description": "Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", "example": "string", + "nullable": true, "type": "string" }, "name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "virtual_path": { "description": "Stable virtual path assigned to the template config. `null` when no virtual path was set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -50663,8 +54646,7 @@ }, "updated_at": { "description": "When the Solution config was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "upgrade_available": { @@ -50675,6 +54657,7 @@ "virtual_path": { "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.", "example": "string", + "nullable": true, "type": "string" } }, @@ -50760,13 +54743,13 @@ }, "created_at": { "description": "When the Solution config was first imported (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "events": { @@ -50782,6 +54765,7 @@ "image_url": { "description": "Absolute URL of the Solution's cover image — the bundled asset the body's `image:` field names. A stable, non-expiring capability URL (like `org_logo.url`), safe to hold in caches and OpenGraph tags; it 404s if the Solution stops declaring a cover. `null` when the Solution has no cover image, and always `null` for org-scoped rows — the permanent URL is minted for system-scope (catalog) Solutions only.", "example": "https://example.com", + "nullable": true, "type": "string" }, "kind": { @@ -50792,16 +54776,19 @@ "latest_solution": { "description": "When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "latest_version": { "description": "When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", "example": "1.0.0", + "nullable": true, "type": "string" }, "lookup_key": { "description": "The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -50814,11 +54801,13 @@ "name": { "description": "Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "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.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_logo": { @@ -50832,40 +54821,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -50874,11 +54871,13 @@ "org_name": { "description": "Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_slug": { "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.", "example": "example-slug", + "nullable": true, "type": "string" }, "owners": { @@ -50894,6 +54893,7 @@ "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "screenshot_urls": { @@ -50909,11 +54909,13 @@ "solution_id": { "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.", "example": "01234567-89ab-cdef-0123-456789abcdef", + "nullable": true, "type": "string" }, "solution_version": { "description": "Semver string declared in the Solution body (e.g. `\"1.2.0\"`). `null` when the body does not declare a version.", "example": "1.2.0", + "nullable": true, "type": "string" }, "tag_keys": { @@ -50929,6 +54931,7 @@ "template_kind": { "description": "Wrapped template kind — `\"AgentTemplate\"`, `\"AutomationTemplate\"`, `\"AgentRoutineTemplate\"`, `\"AgentToolTemplate\"`, `\"AgentComputerTemplate\"`, or `\"SolutionTemplateRef\"` for ref-mode bundles.", "example": "AgentTemplate", + "nullable": true, "type": "string" }, "templates": { @@ -50961,6 +54964,7 @@ "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "details": { @@ -50968,6 +54972,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -50992,12 +54997,13 @@ }, "properties": { "automation_type": { - "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`).", + "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", "example": "string", + "nullable": true, "type": "string" }, "invoke_contract": { - "description": "Schema-driven payload and participant inputs for an invoked automation. Used by installation clients to collect locked prefills before provisioning.", + "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.", "example": { "input_schema": {}, "participants": [ @@ -51013,10 +55019,12 @@ "payload": {} } }, + "nullable": true, "properties": { "input_schema": { "description": "JSON Schema validated against the whole invoke payload, from the automation's `input_schema_config`. `null` when none is configured.", "example": {}, + "nullable": true, "type": "object" }, "participants": { @@ -51037,10 +55045,12 @@ "required": true, "type": "agent_user" }, + "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", "example": "An example description.", + "nullable": true, "type": "string" }, "name": { @@ -51066,6 +55076,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -51114,11 +55125,13 @@ "display_name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "id": { "description": "Template config ID (`cfg_...`). `null` for inline-only templates.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "kind": { @@ -51129,21 +55142,25 @@ "lookup_key": { "description": "Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", "example": "string", + "nullable": true, "type": "string" }, "name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "virtual_path": { "description": "Stable virtual path assigned to the template config. `null` when no virtual path was set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -51156,8 +55173,7 @@ }, "updated_at": { "description": "When the Solution config was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "upgrade_available": { @@ -51168,6 +55184,7 @@ "virtual_path": { "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.", "example": "string", + "nullable": true, "type": "string" } }, @@ -51203,11 +55220,13 @@ "description": { "description": "Description of the template from the config body. `null` if the current version has no `description` field.", "example": "An example description.", + "nullable": true, "type": "string" }, "display_name": { "description": "Human-readable display name from the config body. `null` if the current version has no `display_name` field.", "example": "Example Name", + "nullable": true, "type": "string" }, "id": { @@ -51223,11 +55242,13 @@ "lookup_key": { "description": "Stable lookup key assigned to this template config. `null` if no lookup key is set.", "example": "string", + "nullable": true, "type": "string" }, "name": { "description": "Template name as stored in the config body. `null` if the current version has no `name` field.", "example": "Example Name", + "nullable": true, "type": "string" }, "updated_at": { @@ -51239,6 +55260,7 @@ "virtual_path": { "description": "Virtual filesystem path for this template config. `null` if not set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -51258,22 +55280,24 @@ "team": { "description": "ID of the team that owns this agent (`tem_...`). `null` if the agent is not team-scoped.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "template_upgrade_available": { "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`).", "example": true, + "nullable": true, "type": "boolean" }, "updated_at": { "description": "When the agent was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "user": { "description": "ID of the user that owns this agent (`usr_...`). `null` if the agent is not user-scoped.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" } }, @@ -51309,6 +55333,7 @@ "name": { "description": "Display name of the member, derived from the associated user or agent. `null` if the principal is unknown.", "example": "Example Name", + "nullable": true, "type": "string" }, "profile_picture": { @@ -51322,40 +55347,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -51369,6 +55402,7 @@ "team": { "description": "The team this membership belongs to, as an expanded team object. `null` when the team association is not preloaded.", "example": {}, + "nullable": true, "type": "object" }, "type": { @@ -51388,6 +55422,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -51398,28 +55437,64 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" }, + "nullable": true, "properties": { "alias": { "description": "Short handle or alias for the user. `null` if not set.", "example": "jdoe", + "nullable": true, "type": "string" }, "app": { "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.", "example": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "app_name": { "description": "Display name of the user's app. `null` when the app association was not preloaded by the caller.", "example": "Example Name", + "nullable": true, + "type": "string" + }, + "created_by_agent_user": { + "description": "Agent user that created this account (`usr_...`). `null` unless an agent created it.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_developer": { + "description": "Developer account that created this user (`dva_...`). `null` unless created via a developer token.", + "example": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_org": { + "description": "Org of the principal that created this user (`org_...`). `null` on legacy rows.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_team": { + "description": "Team that created this user (`tem_...`). `null` unless created as a team.", + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_user": { + "description": "User who created this account (`usr_...`). `null` on self-signup or legacy rows.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "email": { "description": "Email address of the user.", "example": "user@example.com", + "nullable": true, "type": "string" }, "id": { @@ -51442,31 +55517,43 @@ "name": { "description": "Full display name of the user. `null` if the user has not set a name.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "description": "ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_name": { "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.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_role": { "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.", "example": "member", + "nullable": true, + "type": "string" + }, + "org_slug": { + "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.", + "example": "example-slug", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "sandbox_name": { "description": "Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.", "example": "Example Name", + "nullable": true, "type": "string" } }, @@ -51507,7 +55594,7 @@ ] }, "post": { - "description": "Adds a user or agent as a member of the specified team and returns the new\nmembership with HTTP 201. Provide exactly one of `user` or `agent` — supplying\nboth or neither returns a 400 error.\n\nThe caller must have permission to manage the team. When an `app` is provided,\nthe request is scoped to that app and the caller must hold a valid app-scoped\ntoken. The default role is `\"member\"` when `role` is omitted.\n", + "description": "Adds a user or agent as a member of the specified team and returns the new\nmembership with HTTP 201. Provide exactly one of `user` or `agent` — supplying\nboth or neither returns a 400 error.\n\nAdding a user requires permission to manage the team (team owner, team\nadmin, or org admin). Adding an agent with the default `\"member\"` role is\nalso open to any existing member of the team; assigning an elevated role to\nan agent still requires team-manage permission. When an `app` is provided,\nthe request is scoped to that app and the caller must hold a valid app-scoped\ntoken. The default role is `\"member\"` when `role` is omitted.\n", "operationId": "post_api_v1_teams__team_members", "parameters": [ { @@ -51784,16 +55871,19 @@ "alias": { "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", "example": "alice", + "nullable": true, "type": "string" }, "id": { "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "nullable": true, "type": "string" }, "name": { "description": "Display name of the actor shown in the UI. `null` if no name is set.", "example": "Example Name", + "nullable": true, "type": "string" }, "profile_picture": { @@ -51807,40 +55897,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -51995,6 +56093,46 @@ "type": "string" } }, + { + "description": "Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_id`.", + "example": "string", + "in": "query", + "name": "source_scope", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Return only tasks whose source matches this object kind. Must be supplied with the other source filters.", + "example": "string", + "in": "query", + "name": "source_type", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Return only tasks whose source matches this object identity. Must be supplied with the other source filters.", + "example": "string", + "in": "query", + "name": "source_id", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Return only tasks with this exact epic label.", + "example": "string", + "in": "query", + "name": "epic", + "required": false, + "schema": { + "type": "string" + } + }, { "description": "Restrict results to tasks whose name or description contains this string.", "example": "string", @@ -52055,6 +56193,16 @@ "type": "boolean" } }, + { + "description": "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.", + "example": true, + "in": "query", + "name": "ready", + "required": false, + "schema": { + "type": "boolean" + } + }, { "description": "Maximum number of tasks to return. Capped at 100.", "example": 1, @@ -52115,6 +56263,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -52144,6 +56293,9 @@ "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "priority": 2, "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", "status": "open", "subtasks_count": 1, "tags": [ @@ -52160,10 +56312,12 @@ "properties": { "after_cursor": { "example": "string", + "nullable": true, "type": "string" }, "before_cursor": { "example": "string", + "nullable": true, "type": "string" }, "data": { @@ -52198,6 +56352,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -52227,6 +56382,9 @@ "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "priority": 2, "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", "status": "open", "subtasks_count": 1, "tags": [ @@ -52269,6 +56427,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -52298,6 +56457,9 @@ "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "priority": 2, "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", "status": "open", "subtasks_count": 1, "tags": [ @@ -52312,6 +56474,7 @@ "agent": { "description": "ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "blocked_by_count": { @@ -52323,6 +56486,7 @@ "description": "When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", "example": "2024-01-01T00:00:00Z", "format": "date-time", + "nullable": true, "type": "string" }, "comments_count": { @@ -52352,20 +56516,24 @@ "width": 800 } }, + "nullable": true, "properties": { "alias": { "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", "example": "alice", + "nullable": true, "type": "string" }, "id": { "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "nullable": true, "type": "string" }, "name": { "description": "Display name of the actor shown in the UI. `null` if no name is set.", "example": "Example Name", + "nullable": true, "type": "string" }, "profile_picture": { @@ -52379,40 +56547,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -52424,11 +56600,13 @@ "created_by_agent": { "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.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "created_by_user": { "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.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "current_lease": { @@ -52467,12 +56645,20 @@ "description": { "description": "Long-form description or notes for the task. `null` if no description has been provided.", "example": "An example description.", + "nullable": true, "type": "string" }, "due_date": { "description": "Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", "example": "2024-01-01T00:00:00Z", "format": "date-time", + "nullable": true, + "type": "string" + }, + "epic": { + "description": "Free-form grouping label. `null` when the task is not in an epic.", + "example": "string", + "nullable": true, "type": "string" }, "id": { @@ -52507,6 +56693,7 @@ "org": { "description": "ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "owner_actor": { @@ -52525,20 +56712,24 @@ "width": 800 } }, + "nullable": true, "properties": { "alias": { "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", "example": "alice", + "nullable": true, "type": "string" }, "id": { "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "nullable": true, "type": "string" }, "name": { "description": "Display name of the actor shown in the UI. `null` if no name is set.", "example": "Example Name", + "nullable": true, "type": "string" }, "profile_picture": { @@ -52552,40 +56743,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -52597,16 +56796,19 @@ "owner_agent": { "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.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "owner_user": { "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.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "parent": { "description": "ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks. Subtasks nest exactly one level.", "example": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "priority": { @@ -52617,6 +56819,25 @@ "sandbox": { "description": "ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "source_id": { + "description": "Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", + "example": "string", + "nullable": true, + "type": "string" + }, + "source_scope": { + "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`.", + "example": "string", + "nullable": true, + "type": "string" + }, + "source_type": { + "description": "Kind of source object (for example `repository`). `null` when the task has no source.", + "example": "string", + "nullable": true, "type": "string" }, "status": { @@ -52642,11 +56863,13 @@ "team": { "description": "ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "thread": { "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.", "example": "thr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "updated_at": { @@ -52658,6 +56881,7 @@ "user": { "description": "ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" } }, @@ -52726,6 +56950,7 @@ "task": { "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "billing-cadence", "links": { "key": "value" }, @@ -52737,6 +56962,9 @@ "owner_user": "string", "parent": "tsk_01j3k5m7n9p2r4s6t8v0w1x2", "priority": 2, + "source_id": "ArchAstro/firstlanding", + "source_scope": "github.com", + "source_type": "repository", "status": "open", "tags": [ "backend", @@ -52762,6 +56990,7 @@ "example": { "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "billing-cadence", "links": { "key": "value" }, @@ -52773,6 +57002,9 @@ "owner_user": "string", "parent": "tsk_01j3k5m7n9p2r4s6t8v0w1x2", "priority": 2, + "source_id": "ArchAstro/firstlanding", + "source_scope": "github.com", + "source_type": "repository", "status": "open", "tags": [ "backend", @@ -52792,6 +57024,11 @@ "format": "date-time", "type": "string" }, + "epic": { + "description": "Optional free-form grouping label.", + "example": "billing-cadence", + "type": "string" + }, "links": { "description": "Arbitrary key-value map of named URLs or references associated with the task (e.g. external ticket links).", "example": { @@ -52831,6 +57068,21 @@ "example": 2, "type": "integer" }, + "source_id": { + "description": "Source object identity (for example `ArchAstro/firstlanding`).", + "example": "ArchAstro/firstlanding", + "type": "string" + }, + "source_scope": { + "description": "Container of the work this task is about (for example `github.com`). Must be supplied with `source_type` and `source_id`.", + "example": "github.com", + "type": "string" + }, + "source_type": { + "description": "Kind of source object (for example `repository`).", + "example": "repository", + "type": "string" + }, "status": { "description": "Initial status for the task. One of `\"open\"`, `\"in_progress\"`, or `\"done\"`. Defaults to `\"open\"` when omitted.", "example": "open", @@ -52998,6 +57250,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -53027,6 +57280,9 @@ "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "priority": 2, "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", "status": "open", "subtasks_count": 1, "tags": [ @@ -53084,6 +57340,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -53113,6 +57370,9 @@ "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "priority": 2, "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", "status": "open", "subtasks_count": 1, "tags": [ @@ -53159,6 +57419,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -53188,6 +57449,9 @@ "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "priority": 2, "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", "status": "open", "subtasks_count": 1, "tags": [ @@ -53233,6 +57497,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -53262,6 +57527,9 @@ "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "priority": 2, "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", "status": "open", "subtasks_count": 1, "tags": [ @@ -53304,6 +57572,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -53333,6 +57602,9 @@ "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "priority": 2, "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", "status": "open", "subtasks_count": 1, "tags": [ @@ -53347,6 +57619,7 @@ "agent": { "description": "ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "blocked_by_count": { @@ -53358,6 +57631,7 @@ "description": "When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", "example": "2024-01-01T00:00:00Z", "format": "date-time", + "nullable": true, "type": "string" }, "comments_count": { @@ -53387,20 +57661,24 @@ "width": 800 } }, + "nullable": true, "properties": { "alias": { "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", "example": "alice", + "nullable": true, "type": "string" }, "id": { "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "nullable": true, "type": "string" }, "name": { "description": "Display name of the actor shown in the UI. `null` if no name is set.", "example": "Example Name", + "nullable": true, "type": "string" }, "profile_picture": { @@ -53414,40 +57692,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -53459,11 +57745,13 @@ "created_by_agent": { "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.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "created_by_user": { "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.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "current_lease": { @@ -53502,12 +57790,20 @@ "description": { "description": "Long-form description or notes for the task. `null` if no description has been provided.", "example": "An example description.", + "nullable": true, "type": "string" }, "due_date": { "description": "Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", "example": "2024-01-01T00:00:00Z", "format": "date-time", + "nullable": true, + "type": "string" + }, + "epic": { + "description": "Free-form grouping label. `null` when the task is not in an epic.", + "example": "string", + "nullable": true, "type": "string" }, "id": { @@ -53542,6 +57838,7 @@ "org": { "description": "ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "owner_actor": { @@ -53560,20 +57857,24 @@ "width": 800 } }, + "nullable": true, "properties": { "alias": { "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", "example": "alice", + "nullable": true, "type": "string" }, "id": { "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "nullable": true, "type": "string" }, "name": { "description": "Display name of the actor shown in the UI. `null` if no name is set.", "example": "Example Name", + "nullable": true, "type": "string" }, "profile_picture": { @@ -53587,40 +57888,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -53632,16 +57941,19 @@ "owner_agent": { "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.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "owner_user": { "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.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "parent": { "description": "ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks. Subtasks nest exactly one level.", "example": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "priority": { @@ -53652,6 +57964,25 @@ "sandbox": { "description": "ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "source_id": { + "description": "Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", + "example": "string", + "nullable": true, + "type": "string" + }, + "source_scope": { + "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`.", + "example": "string", + "nullable": true, + "type": "string" + }, + "source_type": { + "description": "Kind of source object (for example `repository`). `null` when the task has no source.", + "example": "string", + "nullable": true, "type": "string" }, "status": { @@ -53677,11 +58008,13 @@ "team": { "description": "ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "thread": { "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.", "example": "thr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "updated_at": { @@ -53693,6 +58026,7 @@ "user": { "description": "ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" } }, @@ -53858,13 +58192,13 @@ ] } }, - "/api/v1/teams/{team}/tasks/search": { + "/api/v1/teams/{team}/tasks/ready": { "get": { - "description": "Performs a full-text search over tasks owned by the specified user or team and returns\nmatching results. Combine `q` with the optional filters to narrow the result set\nfurther. When no query is provided, the endpoint behaves like a filtered list.\n\nThe `query` field in the response echoes the effective search query.\nUser-authenticated callers may search their personal tasks or tasks for teams\nthey have joined. Privileged callers provide the owner in the route; the owner's\norganization is implied by that principal. An explicit `org` is optional and,\nwhen set, must match the owner's organization.\n", - "operationId": "get_api_v1_teams__team_tasks_search", + "description": "Returns open tasks with no unfinished blockers and no active session lease.\nReadiness is calculated by the server from the current task projection. It is\na snapshot, not a reservation; claim a task lease before starting work.\n\nPass `explain=true` to include every open task with a stable readiness reason.\n", + "operationId": "get_api_v1_teams__team_tasks_ready", "parameters": [ { - "description": "Team ID (`tem_...`). Only tasks belonging to this team are searched.", + "description": "Team ID (`tem_...`) owning the tasks.", "example": "string", "in": "path", "name": "team", @@ -53874,7 +58208,7 @@ } }, { - "description": "User ID (`usr_...`) whose tasks are searched.", + "description": "User ID (`usr_...`) owning the tasks.", "example": "string", "in": "query", "name": "user", @@ -53884,7 +58218,7 @@ } }, { - "description": "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.", + "description": "Optional organization context for privileged callers.", "example": "string", "in": "query", "name": "org", @@ -53894,87 +58228,67 @@ } }, { - "description": "Full-text search query matched against task names and descriptions. Takes precedence over `query` when both are provided.", - "example": "string", - "in": "query", - "name": "q", - "required": false, - "schema": { - "type": "string" - } - }, - { - "description": "Alias for `q`. Use `q` when possible; this parameter exists for compatibility.", - "example": "string", + "description": "Include blocked and actively leased open tasks with exclusion reasons.", + "example": true, "in": "query", - "name": "query", + "name": "explain", "required": false, "schema": { - "type": "string" + "type": "boolean" } }, { - "description": "Filter results by status. One of `\"open\"`, `\"in_progress\"`, or `\"done\"`. Omit to include all statuses.", - "example": "string", + "description": "Only include tasks assigned to the authenticated user.", + "example": true, "in": "query", - "name": "status", + "name": "assigned_to_me", "required": false, "schema": { - "type": "string" + "type": "boolean" } }, { - "description": "Restrict results to tasks assigned to the user with this public ID (`usr_...`).", + "description": "Only include tasks whose source matches this container. Must be supplied with `source_type` and `source_id`.", "example": "string", "in": "query", - "name": "owner_user", + "name": "source_scope", "required": false, "schema": { "type": "string" } }, { - "description": "Restrict results to tasks assigned to the agent with this public ID (`agi_...`).", + "description": "Only include tasks whose source matches this object kind.", "example": "string", "in": "query", - "name": "owner_agent", + "name": "source_type", "required": false, "schema": { "type": "string" } }, { - "description": "Filter results by priority, from 0 (highest) to 4 (lowest).", - "example": 1, - "in": "query", - "name": "priority", - "required": false, - "schema": { - "type": "integer" - } - }, - { - "description": "Return only tasks carrying this tag (matched against the canonical lowercase form).", + "description": "Only include tasks whose source matches this object identity.", "example": "string", "in": "query", - "name": "tag", + "name": "source_id", "required": false, "schema": { "type": "string" } }, { - "description": "Return only subtasks of the given task (`tsk_...`), or pass `none` to return only top-level tasks.", + "description": "Only include tasks with this exact epic label.", "example": "string", "in": "query", - "name": "parent", + "name": "epic", "required": false, "schema": { "type": "string" } }, { - "description": "Maximum number of tasks to return. Capped at 100.", + "description": "Maximum number of readiness entries to return. Capped at 100.", "example": 1, "in": "query", "name": "limit", @@ -53999,96 +58313,16 @@ "content": { "application/json": { "schema": { - "description": "Search results for the owner's tasks.", + "description": "Cursor-paginated readiness results for the owner.", "example": { "after_cursor": "string", + "authoritative": true, "before_cursor": "string", "data": [ { - "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", - "blocked_by_count": 1, - "closed_at": "2024-01-01T00:00:00Z", - "comments_count": 1, - "created_at": "2024-01-01T00:00:00Z", - "created_by_actor": { - "alias": "alice", - "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", - "name": "Example Name", - "profile_picture": { - "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", - "height": 600, - "media": "med_0aBcDeFgHiJkLmNoPqRsTu", - "mime_type": "application/json", - "refresh_url": "https://example.com", - "url": "https://example.com", - "width": 800 - } - }, - "created_by_agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", - "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", - "current_lease": { - "expires_at": "2024-01-01T00:00:00Z", - "harness": "string", - "session_name": "Example Name" - }, - "description": "An example description.", - "due_date": "2024-01-01T00:00:00Z", - "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", - "is_blocked": true, - "links": { - "key": "value" - }, - "metadata": { - "key": "value" - }, - "name": "Example Name", - "org": "org_0aBcDeFgHiJkLmNoPqRsTu", - "owner_actor": { - "alias": "alice", - "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", - "name": "Example Name", - "profile_picture": { - "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", - "height": 600, - "media": "med_0aBcDeFgHiJkLmNoPqRsTu", - "mime_type": "application/json", - "refresh_url": "https://example.com", - "url": "https://example.com", - "width": 800 - } - }, - "owner_agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", - "owner_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", - "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", - "priority": 2, - "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", - "status": "open", - "subtasks_count": 1, - "tags": [ - "string" - ], - "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", - "thread": "thr_0aBcDeFgHiJkLmNoPqRsTu", - "updated_at": "2024-01-01T00:00:00Z", - "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" - } - ], - "has_more": true, - "query": "string" - }, - "properties": { - "after_cursor": { - "example": "string", - "type": "string" - }, - "before_cursor": { - "example": "string", - "type": "string" - }, - "data": { - "description": "Array of task objects matching the query and filters.", - "example": [ - { + "readiness": "ready", + "reason": "open_blockers", + "task": { "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", "blocked_by_count": 1, "closed_at": "2024-01-01T00:00:00Z", @@ -54117,6 +58351,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -54146,6 +58381,9 @@ "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "priority": 2, "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", "status": "open", "subtasks_count": 1, "tags": [ @@ -54156,108 +58394,70 @@ "updated_at": "2024-01-01T00:00:00Z", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" } - ], - "items": { - "description": "A task representing a unit of work, optionally assignable to a user or agent.", - "example": { - "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", - "blocked_by_count": 1, - "closed_at": "2024-01-01T00:00:00Z", - "comments_count": 1, - "created_at": "2024-01-01T00:00:00Z", - "created_by_actor": { - "alias": "alice", - "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", - "name": "Example Name", - "profile_picture": { - "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", - "height": 600, - "media": "med_0aBcDeFgHiJkLmNoPqRsTu", - "mime_type": "application/json", - "refresh_url": "https://example.com", - "url": "https://example.com", - "width": 800 - } - }, - "created_by_agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", - "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", - "current_lease": { - "expires_at": "2024-01-01T00:00:00Z", - "harness": "string", - "session_name": "Example Name" - }, - "description": "An example description.", - "due_date": "2024-01-01T00:00:00Z", - "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", - "is_blocked": true, - "links": { - "key": "value" - }, - "metadata": { - "key": "value" - }, - "name": "Example Name", - "org": "org_0aBcDeFgHiJkLmNoPqRsTu", - "owner_actor": { - "alias": "alice", - "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + } + ], + "has_more": true + }, + "properties": { + "after_cursor": { + "example": "string", + "type": "string" + }, + "authoritative": { + "description": "Always false because projections can lag writes and a later claim can race this read.", + "example": true, + "type": "boolean" + }, + "before_cursor": { + "example": "string", + "type": "string" + }, + "data": { + "example": [ + { + "readiness": "ready", + "reason": "open_blockers", + "task": { + "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "blocked_by_count": 1, + "closed_at": "2024-01-01T00:00:00Z", + "comments_count": 1, + "created_at": "2024-01-01T00:00:00Z", + "created_by_actor": { + "alias": "alice", + "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "name": "Example Name", + "profile_picture": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + } + }, + "created_by_agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "current_lease": { + "expires_at": "2024-01-01T00:00:00Z", + "harness": "string", + "session_name": "Example Name" + }, + "description": "An example description.", + "due_date": "2024-01-01T00:00:00Z", + "epic": "string", + "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "is_blocked": true, + "links": { + "key": "value" + }, + "metadata": { + "key": "value" + }, "name": "Example Name", - "profile_picture": { - "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", - "height": 600, - "media": "med_0aBcDeFgHiJkLmNoPqRsTu", - "mime_type": "application/json", - "refresh_url": "https://example.com", - "url": "https://example.com", - "width": 800 - } - }, - "owner_agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", - "owner_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", - "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", - "priority": 2, - "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", - "status": "open", - "subtasks_count": 1, - "tags": [ - "string" - ], - "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", - "thread": "thr_0aBcDeFgHiJkLmNoPqRsTu", - "updated_at": "2024-01-01T00:00:00Z", - "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" - }, - "properties": { - "agent": { - "description": "ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", - "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "blocked_by_count": { - "description": "Number of tasks marked as blocking this task, whether or not they are done (see `GET /tasks/{task}/blockers`). Computed on list/show reads; create/update responses may lag one read behind.", - "example": 1, - "type": "integer" - }, - "closed_at": { - "description": "When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", - "type": "string" - }, - "comments_count": { - "description": "Total number of comments posted on this task.", - "example": 1, - "type": "integer" - }, - "created_at": { - "description": "When the task was created (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", - "type": "string" - }, - "created_by_actor": { - "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).", - "example": { + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "owner_actor": { "alias": "alice", "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", "name": "Example Name", @@ -54271,166 +58471,72 @@ "width": 800 } }, - "properties": { - "alias": { - "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", - "example": "alice", - "type": "string" - }, - "id": { - "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", - "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", - "type": "string" - }, - "name": { - "description": "Display name of the actor shown in the UI. `null` if no name is set.", - "example": "Example Name", - "type": "string" - }, + "owner_agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "owner_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "priority": 2, + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", + "status": "open", + "subtasks_count": 1, + "tags": [ + "string" + ], + "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "thread": "thr_0aBcDeFgHiJkLmNoPqRsTu", + "updated_at": "2024-01-01T00:00:00Z", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" + } + } + ], + "items": { + "description": "A task plus the server-calculated reason it is or is not ready.", + "example": { + "readiness": "ready", + "reason": "open_blockers", + "task": { + "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "blocked_by_count": 1, + "closed_at": "2024-01-01T00:00:00Z", + "comments_count": 1, + "created_at": "2024-01-01T00:00:00Z", + "created_by_actor": { + "alias": "alice", + "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "name": "Example Name", "profile_picture": { - "description": "Profile picture for the actor. `null` if the actor has no profile picture.", - "example": { - "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", - "height": 600, - "media": "med_0aBcDeFgHiJkLmNoPqRsTu", - "mime_type": "application/json", - "refresh_url": "https://example.com", - "url": "https://example.com", - "width": 800 - }, - "properties": { - "file": { - "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", - "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "height": { - "description": "Height of the image in pixels. `null` if not known.", - "example": 600, - "type": "integer" - }, - "media": { - "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", - "example": "med_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "mime_type": { - "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", - "example": "application/json", - "type": "string" - }, - "refresh_url": { - "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.", - "example": "https://example.com", - "type": "string" - }, - "url": { - "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.", - "example": "https://example.com", - "type": "string" - }, - "width": { - "description": "Width of the image in pixels. `null` if not known.", - "example": 800, - "type": "integer" - } - }, - "type": "object" + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 } }, - "type": "object" - }, - "created_by_agent": { - "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.", - "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "created_by_user": { - "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.", - "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "current_lease": { - "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.", - "example": { + "created_by_agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "current_lease": { "expires_at": "2024-01-01T00:00:00Z", "harness": "string", "session_name": "Example Name" }, - "nullable": true, - "properties": { - "expires_at": { - "description": "Server-calculated lease expiry in ISO 8601 format.", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", - "type": "string" - }, - "harness": { - "description": "Bounded harness identifier for the coding session.", - "example": "string", - "type": "string" - }, - "session_name": { - "description": "Display name supplied by the coding session that holds the lease.", - "example": "Example Name", - "type": "string" - } - }, - "required": [ - "session_name", - "harness", - "expires_at" - ], - "type": "object" - }, - "description": { - "description": "Long-form description or notes for the task. `null` if no description has been provided.", - "example": "An example description.", - "type": "string" - }, - "due_date": { - "description": "Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", - "type": "string" - }, - "id": { - "description": "Task ID (`tsk_...`).", - "example": "tsk_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "is_blocked": { - "description": "`true` while at least one blocking task is not yet done. Informational only — a blocked task can still change status — and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on list/show reads; create/update responses report `false` until the next read.", - "example": true, - "type": "boolean" - }, - "links": { - "description": "Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.", - "example": { + "description": "An example description.", + "due_date": "2024-01-01T00:00:00Z", + "epic": "string", + "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "is_blocked": true, + "links": { "key": "value" }, - "type": "object" - }, - "metadata": { - "description": "Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.", - "example": { + "metadata": { "key": "value" }, - "type": "object" - }, - "name": { - "description": "Human-readable title of the task.", - "example": "Example Name", - "type": "string" - }, - "org": { - "description": "ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", - "example": "org_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "owner_actor": { - "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).", - "example": { + "name": "Example Name", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "owner_actor": { "alias": "alice", "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", "name": "Example Name", @@ -54444,25 +58550,93 @@ "width": 800 } }, - "properties": { - "alias": { - "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", - "example": "alice", - "type": "string" - }, - "id": { - "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", - "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", - "type": "string" - }, - "name": { - "description": "Display name of the actor shown in the UI. `null` if no name is set.", - "example": "Example Name", - "type": "string" - }, - "profile_picture": { - "description": "Profile picture for the actor. `null` if the actor has no profile picture.", - "example": { + "owner_agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "owner_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "priority": 2, + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", + "status": "open", + "subtasks_count": 1, + "tags": [ + "string" + ], + "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "thread": "thr_0aBcDeFgHiJkLmNoPqRsTu", + "updated_at": "2024-01-01T00:00:00Z", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" + } + }, + "properties": { + "readiness": { + "description": "One of `ready`, `blocked`, or `leased`.", + "enum": [ + "ready", + "blocked", + "leased" + ], + "example": "ready", + "type": "string" + }, + "reason": { + "description": "Stable exclusion reason: `open_blockers` or `active_lease`; omitted when ready.", + "enum": [ + "open_blockers", + "active_lease" + ], + "example": "open_blockers", + "nullable": true, + "type": "string" + }, + "task": { + "description": "The task evaluated for readiness.", + "example": { + "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "blocked_by_count": 1, + "closed_at": "2024-01-01T00:00:00Z", + "comments_count": 1, + "created_at": "2024-01-01T00:00:00Z", + "created_by_actor": { + "alias": "alice", + "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "name": "Example Name", + "profile_picture": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + } + }, + "created_by_agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "current_lease": { + "expires_at": "2024-01-01T00:00:00Z", + "harness": "string", + "session_name": "Example Name" + }, + "description": "An example description.", + "due_date": "2024-01-01T00:00:00Z", + "epic": "string", + "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "is_blocked": true, + "links": { + "key": "value" + }, + "metadata": { + "key": "value" + }, + "name": "Example Name", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "owner_actor": { + "alias": "alice", + "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "name": "Example Name", + "profile_picture": { "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", "height": 600, "media": "med_0aBcDeFgHiJkLmNoPqRsTu", @@ -54470,120 +58644,452 @@ "refresh_url": "https://example.com", "url": "https://example.com", "width": 800 + } + }, + "owner_agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "owner_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "priority": 2, + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", + "status": "open", + "subtasks_count": 1, + "tags": [ + "string" + ], + "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "thread": "thr_0aBcDeFgHiJkLmNoPqRsTu", + "updated_at": "2024-01-01T00:00:00Z", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" + }, + "properties": { + "agent": { + "description": "ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", + "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "blocked_by_count": { + "description": "Number of tasks marked as blocking this task, whether or not they are done (see `GET /tasks/{task}/blockers`). Computed on list/show reads; create/update responses may lag one read behind.", + "example": 1, + "type": "integer" + }, + "closed_at": { + "description": "When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "nullable": true, + "type": "string" + }, + "comments_count": { + "description": "Total number of comments posted on this task.", + "example": 1, + "type": "integer" + }, + "created_at": { + "description": "When the task was created (ISO 8601).", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "type": "string" + }, + "created_by_actor": { + "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).", + "example": { + "alias": "alice", + "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "name": "Example Name", + "profile_picture": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + } }, + "nullable": true, "properties": { - "file": { - "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", - "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "alias": { + "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", + "example": "alice", + "nullable": true, "type": "string" }, - "height": { - "description": "Height of the image in pixels. `null` if not known.", - "example": 600, - "type": "integer" + "id": { + "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", + "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "nullable": true, + "type": "string" }, - "media": { - "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", - "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "name": { + "description": "Display name of the actor shown in the UI. `null` if no name is set.", + "example": "Example Name", + "nullable": true, "type": "string" }, - "mime_type": { - "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", - "example": "application/json", + "profile_picture": { + "description": "Profile picture for the actor. `null` if the actor has no profile picture.", + "example": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + }, + "nullable": true, + "properties": { + "file": { + "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", + "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "height": { + "description": "Height of the image in pixels. `null` if not known.", + "example": 600, + "nullable": true, + "type": "integer" + }, + "media": { + "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", + "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "mime_type": { + "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", + "example": "application/json", + "nullable": true, + "type": "string" + }, + "refresh_url": { + "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.", + "example": "https://example.com", + "nullable": true, + "type": "string" + }, + "url": { + "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.", + "example": "https://example.com", + "nullable": true, + "type": "string" + }, + "width": { + "description": "Width of the image in pixels. `null` if not known.", + "example": 800, + "nullable": true, + "type": "integer" + } + }, + "type": "object" + } + }, + "type": "object" + }, + "created_by_agent": { + "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.", + "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_user": { + "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.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "current_lease": { + "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.", + "example": { + "expires_at": "2024-01-01T00:00:00Z", + "harness": "string", + "session_name": "Example Name" + }, + "nullable": true, + "properties": { + "expires_at": { + "description": "Server-calculated lease expiry in ISO 8601 format.", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", "type": "string" }, - "refresh_url": { - "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.", - "example": "https://example.com", + "harness": { + "description": "Bounded harness identifier for the coding session.", + "example": "string", "type": "string" }, - "url": { - "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.", - "example": "https://example.com", + "session_name": { + "description": "Display name supplied by the coding session that holds the lease.", + "example": "Example Name", + "type": "string" + } + }, + "required": [ + "session_name", + "harness", + "expires_at" + ], + "type": "object" + }, + "description": { + "description": "Long-form description or notes for the task. `null` if no description has been provided.", + "example": "An example description.", + "nullable": true, + "type": "string" + }, + "due_date": { + "description": "Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "nullable": true, + "type": "string" + }, + "epic": { + "description": "Free-form grouping label. `null` when the task is not in an epic.", + "example": "string", + "nullable": true, + "type": "string" + }, + "id": { + "description": "Task ID (`tsk_...`).", + "example": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "is_blocked": { + "description": "`true` while at least one blocking task is not yet done. Informational only — a blocked task can still change status — and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on list/show reads; create/update responses report `false` until the next read.", + "example": true, + "type": "boolean" + }, + "links": { + "description": "Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.", + "example": { + "key": "value" + }, + "type": "object" + }, + "metadata": { + "description": "Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.", + "example": { + "key": "value" + }, + "type": "object" + }, + "name": { + "description": "Human-readable title of the task.", + "example": "Example Name", + "type": "string" + }, + "org": { + "description": "ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "owner_actor": { + "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).", + "example": { + "alias": "alice", + "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "name": "Example Name", + "profile_picture": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + } + }, + "nullable": true, + "properties": { + "alias": { + "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", + "example": "alice", + "nullable": true, "type": "string" }, - "width": { - "description": "Width of the image in pixels. `null` if not known.", - "example": 800, - "type": "integer" + "id": { + "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", + "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "nullable": true, + "type": "string" + }, + "name": { + "description": "Display name of the actor shown in the UI. `null` if no name is set.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "profile_picture": { + "description": "Profile picture for the actor. `null` if the actor has no profile picture.", + "example": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + }, + "nullable": true, + "properties": { + "file": { + "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", + "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "height": { + "description": "Height of the image in pixels. `null` if not known.", + "example": 600, + "nullable": true, + "type": "integer" + }, + "media": { + "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", + "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "mime_type": { + "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", + "example": "application/json", + "nullable": true, + "type": "string" + }, + "refresh_url": { + "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.", + "example": "https://example.com", + "nullable": true, + "type": "string" + }, + "url": { + "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.", + "example": "https://example.com", + "nullable": true, + "type": "string" + }, + "width": { + "description": "Width of the image in pixels. `null` if not known.", + "example": 800, + "nullable": true, + "type": "integer" + } + }, + "type": "object" } }, "type": "object" + }, + "owner_agent": { + "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.", + "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "owner_user": { + "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.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "parent": { + "description": "ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks. Subtasks nest exactly one level.", + "example": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "priority": { + "description": "Priority level of the task from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when not explicitly set.", + "example": 2, + "type": "integer" + }, + "sandbox": { + "description": "ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", + "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "source_id": { + "description": "Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", + "example": "string", + "nullable": true, + "type": "string" + }, + "source_scope": { + "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`.", + "example": "string", + "nullable": true, + "type": "string" + }, + "source_type": { + "description": "Kind of source object (for example `repository`). `null` when the task has no source.", + "example": "string", + "nullable": true, + "type": "string" + }, + "status": { + "description": "Current status of the task. One of `\"open\"`, `\"in_progress\"`, or `\"done\"`.", + "example": "open", + "type": "string" + }, + "subtasks_count": { + "description": "Number of subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.", + "example": 1, + "type": "integer" + }, + "tags": { + "description": "Labels for grouping and filtering, stored lowercase and de-duplicated. Empty array when untagged.", + "example": [ + "string" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "team": { + "description": "ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "thread": { + "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.", + "example": "thr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "updated_at": { + "description": "When the task was last modified (ISO 8601).", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "type": "string" + }, + "user": { + "description": "ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" } }, - "type": "object" - }, - "owner_agent": { - "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.", - "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "owner_user": { - "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.", - "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "parent": { - "description": "ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks. Subtasks nest exactly one level.", - "example": "tsk_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "priority": { - "description": "Priority level of the task from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when not explicitly set.", - "example": 2, - "type": "integer" - }, - "sandbox": { - "description": "ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", - "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "status": { - "description": "Current status of the task. One of `\"open\"`, `\"in_progress\"`, or `\"done\"`.", - "example": "open", - "type": "string" - }, - "subtasks_count": { - "description": "Number of subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.", - "example": 1, - "type": "integer" - }, - "tags": { - "description": "Labels for grouping and filtering, stored lowercase and de-duplicated. Empty array when untagged.", - "example": [ - "string" + "required": [ + "id", + "name", + "status" ], - "items": { - "type": "string" - }, - "type": "array" - }, - "team": { - "description": "ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", - "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "thread": { - "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.", - "example": "thr_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "updated_at": { - "description": "When the task was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", - "type": "string" - }, - "user": { - "description": "ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", - "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" + "type": "object" } }, "required": [ - "id", - "name", - "status" + "task", + "readiness" ], "type": "object" }, @@ -54592,16 +59098,12 @@ "has_more": { "example": true, "type": "boolean" - }, - "query": { - "example": "string", - "type": "string" } }, "required": [ "data", - "has_more", - "query" + "authoritative", + "has_more" ], "type": "object" } @@ -54616,23 +59118,23 @@ "description": "Task owner not found" }, "422": { - "description": "Invalid explicit owner or organization context" + "description": "Invalid owner context or pagination cursor" } }, - "summary": "Search an owner's tasks", + "summary": "List an owner's ready tasks", "x-auth": [ "publishable_key", "bearer" ] } }, - "/api/v1/teams/{team}/threads": { + "/api/v1/teams/{team}/tasks/search": { "get": { - "description": "Returns all threads owned by the specified team that the authenticated caller\nhas permission to view. The caller must have access to the team; requests\nwithout team access are rejected with 404.\n\nThreads are returned in a single `data` array, ordered with the team's\ndefault thread first, then by most recent activity (newest first). Each\nthread carries a `last_activity` timestamp — the most recent message's\ncreation time, falling back to the thread's own creation time. Use the\nteam-scoped thread endpoints to create, update, or delete individual\nthreads.\n", - "operationId": "get_api_v1_teams__team_threads", + "description": "Performs a full-text search over tasks owned by the specified user or team and returns\nmatching results. Combine `q` with the optional filters to narrow the result set\nfurther. When no query is provided, the endpoint behaves like a filtered list.\n\nThe `query` field in the response echoes the effective search query.\nUser-authenticated callers may search their personal tasks or tasks for teams\nthey have joined. Privileged callers provide the owner in the route; the owner's\norganization is implied by that principal. An explicit `org` is optional and,\nwhen set, must match the owner's organization.\n", + "operationId": "get_api_v1_teams__team_tasks_search", "parameters": [ { - "description": "Team ID (`tem_...`) whose threads should be listed.", + "description": "Team ID (`tem_...`). Only tasks belonging to this team are searched.", "example": "string", "in": "path", "name": "team", @@ -54642,18 +59144,163 @@ } }, { - "description": "Optional: only return threads tagged with at least one of these tags (OR-match). Repeated query params, e.g. `?tags[]=blocked&tags[]=needs-review`.", - "example": [ - "string" - ], + "description": "User ID (`usr_...`) whose tasks are searched.", + "example": "string", "in": "query", - "name": "tags", + "name": "user", "required": false, "schema": { - "items": { - "type": "string" - }, - "type": "array" + "type": "string" + } + }, + { + "description": "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.", + "example": "string", + "in": "query", + "name": "org", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Full-text search query matched against task names and descriptions. Takes precedence over `query` when both are provided.", + "example": "string", + "in": "query", + "name": "q", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Alias for `q`. Use `q` when possible; this parameter exists for compatibility.", + "example": "string", + "in": "query", + "name": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Filter results by status. One of `\"open\"`, `\"in_progress\"`, or `\"done\"`. Omit to include all statuses.", + "example": "string", + "in": "query", + "name": "status", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Restrict results to tasks assigned to the user with this public ID (`usr_...`).", + "example": "string", + "in": "query", + "name": "owner_user", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Restrict results to tasks assigned to the agent with this public ID (`agi_...`).", + "example": "string", + "in": "query", + "name": "owner_agent", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Filter results by priority, from 0 (highest) to 4 (lowest).", + "example": 1, + "in": "query", + "name": "priority", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "description": "Return only tasks carrying this tag (matched against the canonical lowercase form).", + "example": "string", + "in": "query", + "name": "tag", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Return only subtasks of the given task (`tsk_...`), or pass `none` to return only top-level tasks.", + "example": "string", + "in": "query", + "name": "parent", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_id`.", + "example": "string", + "in": "query", + "name": "source_scope", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Return only tasks whose source matches this object kind.", + "example": "string", + "in": "query", + "name": "source_type", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Return only tasks whose source matches this object identity.", + "example": "string", + "in": "query", + "name": "source_id", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Return only tasks with this exact epic label.", + "example": "string", + "in": "query", + "name": "epic", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Maximum number of tasks to return. Capped at 100.", + "example": 1, + "in": "query", + "name": "limit", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "description": "Opaque cursor returned by the previous page.", + "example": "string", + "in": "query", + "name": "after_cursor", + "required": false, + "schema": { + "type": "string" } } ], @@ -54662,60 +59309,279 @@ "content": { "application/json": { "schema": { - "description": "Response envelope containing the team's threads.", + "description": "Search results for the owner's tasks.", "example": { + "after_cursor": "string", + "before_cursor": "string", "data": [ { - "agent_user": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "blocked_by_count": 1, + "closed_at": "2024-01-01T00:00:00Z", + "comments_count": 1, "created_at": "2024-01-01T00:00:00Z", - "creator": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_actor": { + "alias": "alice", + "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "name": "Example Name", + "profile_picture": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + } + }, + "created_by_agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "current_lease": { + "expires_at": "2024-01-01T00:00:00Z", + "harness": "string", + "session_name": "Example Name" + }, "description": "An example description.", - "id": "string", - "is_channel": true, - "is_default": true, - "is_transient": true, - "is_unlisted": true, - "key": "string", - "kind": "string", - "last_activity": "2024-01-01T00:00:00Z", - "last_message_preview": "Sounds good — I'll ship the fix tomorrow.", - "last_message_sender": "Alice Chen", + "due_date": "2024-01-01T00:00:00Z", + "epic": "string", + "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "is_blocked": true, + "links": { + "key": "value" + }, "metadata": { "key": "value" }, - "muted": true, + "name": "Example Name", "org": "org_0aBcDeFgHiJkLmNoPqRsTu", - "parent_message": { - "acl": { - "add": [ - { - "actions": [ - "read", - "write" - ], - "principal": "string", - "principal_type": "user" - } - ], - "grants": [ - { - "actions": [ - "read", - "write" - ], - "principal": "string", - "principal_type": "user" - } - ], - "remove": [ - { - "principal": "string", - "principal_type": "user" - } - ] + "owner_actor": { + "alias": "alice", + "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "name": "Example Name", + "profile_picture": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + } + }, + "owner_agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "owner_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "priority": 2, + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", + "status": "open", + "subtasks_count": 1, + "tags": [ + "string" + ], + "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "thread": "thr_0aBcDeFgHiJkLmNoPqRsTu", + "updated_at": "2024-01-01T00:00:00Z", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" + } + ], + "has_more": true, + "query": "string" + }, + "properties": { + "after_cursor": { + "example": "string", + "type": "string" + }, + "before_cursor": { + "example": "string", + "type": "string" + }, + "data": { + "description": "Array of task objects matching the query and filters.", + "example": [ + { + "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "blocked_by_count": 1, + "closed_at": "2024-01-01T00:00:00Z", + "comments_count": 1, + "created_at": "2024-01-01T00:00:00Z", + "created_by_actor": { + "alias": "alice", + "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "name": "Example Name", + "profile_picture": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + } }, - "actors": [ - { + "created_by_agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "current_lease": { + "expires_at": "2024-01-01T00:00:00Z", + "harness": "string", + "session_name": "Example Name" + }, + "description": "An example description.", + "due_date": "2024-01-01T00:00:00Z", + "epic": "string", + "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "is_blocked": true, + "links": { + "key": "value" + }, + "metadata": { + "key": "value" + }, + "name": "Example Name", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "owner_actor": { + "alias": "alice", + "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "name": "Example Name", + "profile_picture": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + } + }, + "owner_agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "owner_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "priority": 2, + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", + "status": "open", + "subtasks_count": 1, + "tags": [ + "string" + ], + "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "thread": "thr_0aBcDeFgHiJkLmNoPqRsTu", + "updated_at": "2024-01-01T00:00:00Z", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" + } + ], + "items": { + "description": "A task representing a unit of work, optionally assignable to a user or agent.", + "example": { + "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "blocked_by_count": 1, + "closed_at": "2024-01-01T00:00:00Z", + "comments_count": 1, + "created_at": "2024-01-01T00:00:00Z", + "created_by_actor": { + "alias": "alice", + "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "name": "Example Name", + "profile_picture": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + } + }, + "created_by_agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "current_lease": { + "expires_at": "2024-01-01T00:00:00Z", + "harness": "string", + "session_name": "Example Name" + }, + "description": "An example description.", + "due_date": "2024-01-01T00:00:00Z", + "epic": "string", + "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "is_blocked": true, + "links": { + "key": "value" + }, + "metadata": { + "key": "value" + }, + "name": "Example Name", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "owner_actor": { + "alias": "alice", + "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "name": "Example Name", + "profile_picture": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + } + }, + "owner_agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "owner_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "priority": 2, + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", + "status": "open", + "subtasks_count": 1, + "tags": [ + "string" + ], + "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "thread": "thr_0aBcDeFgHiJkLmNoPqRsTu", + "updated_at": "2024-01-01T00:00:00Z", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" + }, + "properties": { + "agent": { + "description": "ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", + "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "blocked_by_count": { + "description": "Number of tasks marked as blocking this task, whether or not they are done (see `GET /tasks/{task}/blockers`). Computed on list/show reads; create/update responses may lag one read behind.", + "example": 1, + "type": "integer" + }, + "closed_at": { + "description": "When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "nullable": true, + "type": "string" + }, + "comments_count": { + "description": "Total number of comments posted on this task.", + "example": 1, + "type": "integer" + }, + "created_at": { + "description": "When the task was created (ISO 8601).", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "type": "string" + }, + "created_by_actor": { + "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).", + "example": { "alias": "alice", "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", "name": "Example Name", @@ -54728,59 +59594,577 @@ "url": "https://example.com", "width": 800 } - } - ], - "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", - "agent_mode": "cli", - "attachments": [ - { - "content_type": "application/json", - "description": "An example description.", - "filename": "string", - "height": 1, - "id": "string", - "image_height": 1, - "image_source": { - "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", - "height": 600, - "media": "med_0aBcDeFgHiJkLmNoPqRsTu", - "mime_type": "application/json", - "refresh_url": "https://example.com", - "url": "https://example.com", - "width": 800 + }, + "nullable": true, + "properties": { + "alias": { + "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", + "example": "alice", + "nullable": true, + "type": "string" }, - "image_url": "https://example.com", - "image_width": 1, - "media_type": "application/json", - "name": "Example Name", - "object": {}, - "title": "Example Title", - "type": "file", - "url": "https://example.com", - "variants": [ - { - "content_type": "application/json", - "created_at": "2024-01-01T00:00:00Z", + "id": { + "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", + "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "nullable": true, + "type": "string" + }, + "name": { + "description": "Display name of the actor shown in the UI. `null` if no name is set.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "profile_picture": { + "description": "Profile picture for the actor. `null` if the actor has no profile picture.", + "example": { "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", - "filename": "string", "height": 600, - "id": "mvr_0aBcDeFgHiJkLmNoPqRsTu", - "image_source": { - "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", - "height": 600, - "media": "med_0aBcDeFgHiJkLmNoPqRsTu", - "mime_type": "application/json", - "refresh_url": "https://example.com", - "url": "https://example.com", - "width": 800 - }, - "updated_at": "2024-01-01T00:00:00Z", + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", "url": "https://example.com", - "variant_key": "original", "width": 800 - } - ], - "version": 1, + }, + "nullable": true, + "properties": { + "file": { + "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", + "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "height": { + "description": "Height of the image in pixels. `null` if not known.", + "example": 600, + "nullable": true, + "type": "integer" + }, + "media": { + "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", + "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "mime_type": { + "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", + "example": "application/json", + "nullable": true, + "type": "string" + }, + "refresh_url": { + "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.", + "example": "https://example.com", + "nullable": true, + "type": "string" + }, + "url": { + "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.", + "example": "https://example.com", + "nullable": true, + "type": "string" + }, + "width": { + "description": "Width of the image in pixels. `null` if not known.", + "example": 800, + "nullable": true, + "type": "integer" + } + }, + "type": "object" + } + }, + "type": "object" + }, + "created_by_agent": { + "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.", + "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_user": { + "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.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "current_lease": { + "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.", + "example": { + "expires_at": "2024-01-01T00:00:00Z", + "harness": "string", + "session_name": "Example Name" + }, + "nullable": true, + "properties": { + "expires_at": { + "description": "Server-calculated lease expiry in ISO 8601 format.", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "type": "string" + }, + "harness": { + "description": "Bounded harness identifier for the coding session.", + "example": "string", + "type": "string" + }, + "session_name": { + "description": "Display name supplied by the coding session that holds the lease.", + "example": "Example Name", + "type": "string" + } + }, + "required": [ + "session_name", + "harness", + "expires_at" + ], + "type": "object" + }, + "description": { + "description": "Long-form description or notes for the task. `null` if no description has been provided.", + "example": "An example description.", + "nullable": true, + "type": "string" + }, + "due_date": { + "description": "Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "nullable": true, + "type": "string" + }, + "epic": { + "description": "Free-form grouping label. `null` when the task is not in an epic.", + "example": "string", + "nullable": true, + "type": "string" + }, + "id": { + "description": "Task ID (`tsk_...`).", + "example": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "is_blocked": { + "description": "`true` while at least one blocking task is not yet done. Informational only — a blocked task can still change status — and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on list/show reads; create/update responses report `false` until the next read.", + "example": true, + "type": "boolean" + }, + "links": { + "description": "Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.", + "example": { + "key": "value" + }, + "type": "object" + }, + "metadata": { + "description": "Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.", + "example": { + "key": "value" + }, + "type": "object" + }, + "name": { + "description": "Human-readable title of the task.", + "example": "Example Name", + "type": "string" + }, + "org": { + "description": "ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "owner_actor": { + "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).", + "example": { + "alias": "alice", + "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "name": "Example Name", + "profile_picture": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + } + }, + "nullable": true, + "properties": { + "alias": { + "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", + "example": "alice", + "nullable": true, + "type": "string" + }, + "id": { + "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", + "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "nullable": true, + "type": "string" + }, + "name": { + "description": "Display name of the actor shown in the UI. `null` if no name is set.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "profile_picture": { + "description": "Profile picture for the actor. `null` if the actor has no profile picture.", + "example": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + }, + "nullable": true, + "properties": { + "file": { + "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", + "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "height": { + "description": "Height of the image in pixels. `null` if not known.", + "example": 600, + "nullable": true, + "type": "integer" + }, + "media": { + "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", + "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "mime_type": { + "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", + "example": "application/json", + "nullable": true, + "type": "string" + }, + "refresh_url": { + "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.", + "example": "https://example.com", + "nullable": true, + "type": "string" + }, + "url": { + "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.", + "example": "https://example.com", + "nullable": true, + "type": "string" + }, + "width": { + "description": "Width of the image in pixels. `null` if not known.", + "example": 800, + "nullable": true, + "type": "integer" + } + }, + "type": "object" + } + }, + "type": "object" + }, + "owner_agent": { + "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.", + "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "owner_user": { + "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.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "parent": { + "description": "ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks. Subtasks nest exactly one level.", + "example": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "priority": { + "description": "Priority level of the task from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when not explicitly set.", + "example": 2, + "type": "integer" + }, + "sandbox": { + "description": "ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", + "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "source_id": { + "description": "Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", + "example": "string", + "nullable": true, + "type": "string" + }, + "source_scope": { + "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`.", + "example": "string", + "nullable": true, + "type": "string" + }, + "source_type": { + "description": "Kind of source object (for example `repository`). `null` when the task has no source.", + "example": "string", + "nullable": true, + "type": "string" + }, + "status": { + "description": "Current status of the task. One of `\"open\"`, `\"in_progress\"`, or `\"done\"`.", + "example": "open", + "type": "string" + }, + "subtasks_count": { + "description": "Number of subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.", + "example": 1, + "type": "integer" + }, + "tags": { + "description": "Labels for grouping and filtering, stored lowercase and de-duplicated. Empty array when untagged.", + "example": [ + "string" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "team": { + "description": "ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "thread": { + "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.", + "example": "thr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "updated_at": { + "description": "When the task was last modified (ISO 8601).", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "type": "string" + }, + "user": { + "description": "ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + } + }, + "required": [ + "id", + "name", + "status" + ], + "type": "object" + }, + "type": "array" + }, + "has_more": { + "example": true, + "type": "boolean" + }, + "query": { + "example": "string", + "type": "string" + } + }, + "required": [ + "data", + "has_more", + "query" + ], + "type": "object" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "404": { + "description": "Task owner not found" + }, + "422": { + "description": "Invalid explicit owner or organization context" + } + }, + "summary": "Search an owner's tasks", + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/teams/{team}/threads": { + "get": { + "description": "Returns all threads owned by the specified team that the authenticated caller\nhas permission to view. The caller must have access to the team; requests\nwithout team access are rejected with 404.\n\nThreads are returned in a single `data` array, ordered with the team's\ndefault thread first, then by most recent activity (newest first). Each\nthread carries a `last_activity` timestamp — the most recent message's\ncreation time, falling back to the thread's own creation time. Use the\nteam-scoped thread endpoints to create, update, or delete individual\nthreads.\n", + "operationId": "get_api_v1_teams__team_threads", + "parameters": [ + { + "description": "Team ID (`tem_...`) whose threads should be listed.", + "example": "string", + "in": "path", + "name": "team", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Optional: only return threads tagged with at least one of these tags (OR-match). Repeated query params, e.g. `?tags[]=blocked&tags[]=needs-review`.", + "example": [ + "string" + ], + "in": "query", + "name": "tags", + "required": false, + "schema": { + "items": { + "type": "string" + }, + "type": "array" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "description": "Response envelope containing the team's threads.", + "example": { + "data": [ + { + "agent_user": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "created_at": "2024-01-01T00:00:00Z", + "creator": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "description": "An example description.", + "id": "string", + "is_channel": true, + "is_default": true, + "is_transient": true, + "is_unlisted": true, + "key": "string", + "kind": "string", + "last_activity": "2024-01-01T00:00:00Z", + "last_message_preview": "Sounds good — I'll ship the fix tomorrow.", + "last_message_sender": "Alice Chen", + "metadata": { + "key": "value" + }, + "muted": true, + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "parent_message": { + "acl": { + "add": [ + { + "actions": [ + "read", + "write" + ], + "principal": "string", + "principal_type": "user" + } + ], + "grants": [ + { + "actions": [ + "read", + "write" + ], + "principal": "string", + "principal_type": "user" + } + ], + "remove": [ + { + "principal": "string", + "principal_type": "user" + } + ] + }, + "actors": [ + { + "alias": "alice", + "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "name": "Example Name", + "profile_picture": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + } + } + ], + "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "agent_mode": "cli", + "attachments": [ + { + "content_type": "application/json", + "description": "An example description.", + "filename": "string", + "height": 1, + "id": "string", + "image_height": 1, + "image_source": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + }, + "image_url": "https://example.com", + "image_width": 1, + "media_type": "application/json", + "name": "Example Name", + "object": {}, + "title": "Example Title", + "type": "file", + "url": "https://example.com", + "variants": [ + { + "content_type": "application/json", + "created_at": "2024-01-01T00:00:00Z", + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "filename": "string", + "height": 600, + "id": "mvr_0aBcDeFgHiJkLmNoPqRsTu", + "image_source": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + }, + "updated_at": "2024-01-01T00:00:00Z", + "url": "https://example.com", + "variant_key": "original", + "width": 800 + } + ], + "version": 1, "width": 1 } ], @@ -54818,7 +60202,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "participant": [ @@ -54829,6 +60213,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -54839,6 +60228,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -55044,7 +60434,7 @@ ], "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "title": "Example Title", - "ttl": 3600, + "ttl": "2026-08-15T12:00:00", "unread_count": 5, "updated_at": "2024-01-01T00:00:00Z", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", @@ -55209,7 +60599,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "participant": [ @@ -55220,6 +60610,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -55230,6 +60625,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -55435,7 +60831,7 @@ ], "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "title": "Example Title", - "ttl": 3600, + "ttl": "2026-08-15T12:00:00", "unread_count": 5, "updated_at": "2024-01-01T00:00:00Z", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", @@ -55446,7 +60842,7 @@ "description": "A chat thread, representing a conversation channel that can be owned by a user, team, or agent and may contain messages, participants, and AI agent activity.", "example": { "agent_user": "agi_0aBcDeFgHiJkLmNoPqRsTu", - "created_at": "2024-01-01T00:00:00Z", + "created_at": "string", "creator": "usr_0aBcDeFgHiJkLmNoPqRsTu", "description": "An example description.", "id": "string", @@ -55456,7 +60852,7 @@ "is_unlisted": true, "key": "string", "kind": "string", - "last_activity": "2024-01-01T00:00:00Z", + "last_activity": "string", "last_message_preview": "Sounds good — I'll ship the fix tomorrow.", "last_message_sender": "Alice Chen", "metadata": { @@ -55597,7 +60993,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "participant": [ @@ -55608,6 +61004,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -55618,6 +61019,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -55823,9 +61225,9 @@ ], "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "title": "Example Title", - "ttl": 3600, + "ttl": "2026-08-15T12:00:00", "unread_count": 5, - "updated_at": "2024-01-01T00:00:00Z", + "updated_at": "string", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "team" }, @@ -55833,17 +61235,18 @@ "agent_user": { "description": "ID of the agent that owns this thread (`agt_...`). `null` for user-owned or team-owned threads.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "created_at": { "description": "When the thread was created (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "creator": { "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.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "oneOf": [ { "type": "string" @@ -55854,6 +61257,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -55864,6 +61272,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" }, @@ -55871,21 +61280,55 @@ "alias": { "description": "Short handle or alias for the user. `null` if not set.", "example": "jdoe", + "nullable": true, "type": "string" }, "app": { "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.", "example": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "app_name": { "description": "Display name of the user's app. `null` when the app association was not preloaded by the caller.", "example": "Example Name", + "nullable": true, + "type": "string" + }, + "created_by_agent_user": { + "description": "Agent user that created this account (`usr_...`). `null` unless an agent created it.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_developer": { + "description": "Developer account that created this user (`dva_...`). `null` unless created via a developer token.", + "example": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_org": { + "description": "Org of the principal that created this user (`org_...`). `null` on legacy rows.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_team": { + "description": "Team that created this user (`tem_...`). `null` unless created as a team.", + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_user": { + "description": "User who created this account (`usr_...`). `null` on self-signup or legacy rows.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "email": { "description": "Email address of the user.", "example": "user@example.com", + "nullable": true, "type": "string" }, "id": { @@ -55908,31 +61351,43 @@ "name": { "description": "Full display name of the user. `null` if the user has not set a name.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "description": "ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_name": { "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.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_role": { "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.", "example": "member", + "nullable": true, + "type": "string" + }, + "org_slug": { + "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.", + "example": "example-slug", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "sandbox_name": { "description": "Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.", "example": "Example Name", + "nullable": true, "type": "string" } }, @@ -55946,6 +61401,7 @@ "description": { "description": "Optional description or purpose statement for the thread. `null` if not set.", "example": "An example description.", + "nullable": true, "type": "string" }, "id": { @@ -55976,27 +61432,31 @@ "key": { "description": "Application-defined stable key that uniquely identifies the thread within its scope. Useful for idempotent creation. `null` if not set.", "example": "string", + "nullable": true, "type": "string" }, "kind": { - "description": "Thread subtype: `\"standard\"` for ordinary threads, `\"slack_mirror\"` for the membership-strict mirror of a Slack channel, `\"slashwork_mirror\"` for the membership-strict mirror of a Slashwork group. Read-only — derived server-side at creation, never accepted from params.", + "description": "Thread subtype: `\"standard\"` for ordinary threads, `\"personal\"` for a user-and-owned-agents roster, `\"slack_mirror\"` for the membership-strict mirror of a Slack channel, or `\"slashwork_mirror\"` for the membership-strict mirror of a Slashwork group. `personal` is an explicit user-thread creation option; mirror kinds are server-derived.", "example": "string", + "nullable": true, "type": "string" }, "last_activity": { "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.", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", + "nullable": true, "type": "string" }, "last_message_preview": { "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.", "example": "Sounds good — I'll ship the fix tomorrow.", + "nullable": true, "type": "string" }, "last_message_sender": { "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.", "example": "Alice Chen", + "nullable": true, "type": "string" }, "metadata": { @@ -56004,6 +61464,7 @@ "example": { "key": "value" }, + "nullable": true, "type": "object" }, "muted": { @@ -56014,6 +61475,7 @@ "org": { "description": "ID of the organization this thread belongs to (`org_...`). `null` for threads outside an org context.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "parent_message": { @@ -56151,9 +61613,10 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, + "nullable": true, "properties": { "acl": { "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.", @@ -56185,6 +61648,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -56366,16 +61830,19 @@ "alias": { "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", "example": "alice", + "nullable": true, "type": "string" }, "id": { "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "nullable": true, "type": "string" }, "name": { "description": "Display name of the actor shown in the UI. `null` if no name is set.", "example": "Example Name", + "nullable": true, "type": "string" }, "profile_picture": { @@ -56389,40 +61856,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -56436,6 +61911,7 @@ "agent": { "description": "ID of the agent user that sent this message (`agi_...`). `null` for messages sent by human users.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "agent_mode": { @@ -56445,6 +61921,7 @@ "embedded" ], "example": "cli", + "nullable": true, "type": "string" }, "attachments": { @@ -56557,21 +62034,25 @@ "content_type": { "description": "MIME type of the attached file, e.g. `\"image/png\"` or `\"application/pdf\"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.", "example": "application/json", + "nullable": true, "type": "string" }, "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "filename": { "description": "Original filename of the attached file, e.g. `\"report.pdf\"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.", "example": "string", + "nullable": true, "type": "string" }, "height": { "description": "Height in pixels of the media item. Present on `media` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "id": { @@ -56582,6 +62063,7 @@ "image_height": { "description": "Height in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "image_source": { @@ -56595,40 +62077,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -56637,31 +62127,35 @@ "image_url": { "description": "URL of the preview image extracted from the scraped page. Present on `scraped_link` type only. `null` otherwise.", "example": "https://example.com", + "nullable": true, "type": "string" }, "image_width": { "description": "Width in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "media_type": { - "description": "The media category, e.g. `\"video\"` or `\"audio\"`. Present on `media` type only. `null` otherwise.", + "description": "The media category, e.g. `\"video\"` or `\"audio\"`. Present on `media` type only; omitted otherwise.", "example": "application/json", "type": "string" }, "name": { "description": "Display name of the media item. Present on `media` type only. `null` otherwise.", "example": "Example Name", + "nullable": true, "type": "string" }, "object": { - "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`. `null` on other types.", + "description": "The full embedded object payload. For `task` type, contains the task record. For `action` type, contains the action definition. For `chart` type, contains the chart with its inline `spec`. Omitted on other types.", "example": {}, "type": "object" }, "title": { "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.", "example": "Example Title", + "nullable": true, "type": "string" }, "type": { @@ -56672,10 +62166,11 @@ "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "variants": { - "description": "Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only. `null` otherwise.", + "description": "Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only; omitted otherwise.", "example": [ { "content_type": "application/json", @@ -56726,6 +62221,7 @@ "content_type": { "description": "MIME type of this variant's file (e.g., `\"image/jpeg\"`, `\"video/mp4\"`). `null` if the file is not loaded.", "example": "application/json", + "nullable": true, "type": "string" }, "created_at": { @@ -56742,11 +62238,13 @@ "filename": { "description": "Original filename of the uploaded file for this variant. `null` if the file is not loaded.", "example": "string", + "nullable": true, "type": "string" }, "height": { "description": "Height of this variant in pixels. `null` if not recorded.", "example": 600, + "nullable": true, "type": "integer" }, "id": { @@ -56765,40 +62263,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -56813,6 +62319,7 @@ "url": { "description": "Signed download URL for this variant, resolved at request time. `null` if the file is unavailable.", "example": "https://example.com", + "nullable": true, "type": "string" }, "variant_key": { @@ -56823,6 +62330,7 @@ "width": { "description": "Width of this variant in pixels. `null` if not recorded.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -56836,11 +62344,13 @@ "version": { "description": "Version number of the attached artifact at the time of attachment. Present on `artifact` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "width": { "description": "Width in pixels of the media item. Present on `media` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" } }, @@ -56855,17 +62365,18 @@ "branched_thread": { "description": "ID of the thread that was branched from this message (`thr_...`). `null` if this message has not spawned a branch thread.", "example": "string", + "nullable": true, "type": "string" }, "content": { "description": "Text content of the message. `null` for messages that contain only attachments.", "example": "Hello, how can I help you today?", + "nullable": true, "type": "string" }, "created_at": { "description": "When the message was posted (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "has_replies": { @@ -56881,6 +62392,7 @@ "idempotency_key": { "description": "Client-supplied idempotency key used to deduplicate message sends. `null` if the sender did not provide one.", "example": "01234567-89ab-cdef-0123-456789abcdef", + "nullable": true, "type": "string" }, "is_deleted": { @@ -56891,6 +62403,7 @@ "legacy_agent": { "description": "Identifier of the legacy chat agent that sent this message, if applicable. `null` for messages sent by users or modern agent users.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -56903,6 +62416,7 @@ "org": { "description": "ID of the organization that owns this message (`org_...`).", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "reactions": { @@ -56954,6 +62468,7 @@ "rendering_mode": { "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.", "example": "reply", + "nullable": true, "type": "string" }, "replies": { @@ -56969,11 +62484,13 @@ "replies_after_cursor": { "description": "Opaque pagination cursor to fetch replies posted after the current page. Only present when inline replies are included in the response.", "example": "string", + "nullable": true, "type": "string" }, "replies_before_cursor": { "description": "Opaque pagination cursor to fetch replies posted before the current page. Only present when inline replies are included in the response.", "example": "string", + "nullable": true, "type": "string" }, "reply_count": { @@ -57116,9 +62633,10 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, + "nullable": true, "type": "object" }, "root_message_id": { @@ -57130,27 +62648,180 @@ "sandbox": { "description": "ID of the developer sandbox this message belongs to (`dsb_...`). `null` for non-sandbox messages.", "example": "string", + "nullable": true, "type": "string" }, "team": { "description": "ID of the team this message is scoped to (`tem_...`). `null` if the message is not team-scoped.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "thread": { - "description": "ID of the thread this message belongs to (`thr_...`). `null` for messages not yet associated with a thread.", + "description": "ID of the thread this message belongs to (`thr_...`).", "example": "string", "type": "string" }, "type": { "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.", "example": "note", + "nullable": true, "type": "string" }, "user": { "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.", - "example": "string", - "type": "string" + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "oneOf": [ + { + "type": "string" + }, + { + "description": "A platform user account. Represents a human or system actor that can own threads, belong to an organization, and interact with the API.", + "example": { + "alias": "jdoe", + "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "email": "user@example.com", + "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "is_system_user": true, + "metadata": { + "key": "value" + }, + "name": "Example Name", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "org_name": "Example Name", + "org_role": "member", + "org_slug": "example-slug", + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "sandbox_name": "Example Name" + }, + "properties": { + "alias": { + "description": "Short handle or alias for the user. `null` if not set.", + "example": "jdoe", + "nullable": true, + "type": "string" + }, + "app": { + "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.", + "example": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "app_name": { + "description": "Display name of the user's app. `null` when the app association was not preloaded by the caller.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "created_by_agent_user": { + "description": "Agent user that created this account (`usr_...`). `null` unless an agent created it.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_developer": { + "description": "Developer account that created this user (`dva_...`). `null` unless created via a developer token.", + "example": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_org": { + "description": "Org of the principal that created this user (`org_...`). `null` on legacy rows.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_team": { + "description": "Team that created this user (`tem_...`). `null` unless created as a team.", + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_user": { + "description": "User who created this account (`usr_...`). `null` on self-signup or legacy rows.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "email": { + "description": "Email address of the user.", + "example": "user@example.com", + "nullable": true, + "type": "string" + }, + "id": { + "description": "User ID (`usr_...`).", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "is_system_user": { + "description": "`true` if this account is an internal system user rather than a human. System users are created automatically by the platform.", + "example": true, + "type": "boolean" + }, + "metadata": { + "description": "Arbitrary key-value metadata attached to the user. Defaults to an empty object.", + "example": { + "key": "value" + }, + "type": "object" + }, + "name": { + "description": "Full display name of the user. `null` if the user has not set a name.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "org": { + "description": "ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "org_name": { + "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.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "org_role": { + "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.", + "example": "member", + "nullable": true, + "type": "string" + }, + "org_slug": { + "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.", + "example": "example-slug", + "nullable": true, + "type": "string" + }, + "sandbox": { + "description": "ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.", + "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "sandbox_name": { + "description": "Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.", + "example": "Example Name", + "nullable": true, + "type": "string" + } + }, + "required": [ + "id" + ], + "type": "object" + } + ] }, "visibility": { "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.", @@ -57184,6 +62855,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -57194,6 +62870,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -57204,6 +62881,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -57214,6 +62896,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" }, @@ -57221,21 +62904,55 @@ "alias": { "description": "Short handle or alias for the user. `null` if not set.", "example": "jdoe", + "nullable": true, "type": "string" }, "app": { "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.", "example": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "app_name": { "description": "Display name of the user's app. `null` when the app association was not preloaded by the caller.", "example": "Example Name", + "nullable": true, + "type": "string" + }, + "created_by_agent_user": { + "description": "Agent user that created this account (`usr_...`). `null` unless an agent created it.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_developer": { + "description": "Developer account that created this user (`dva_...`). `null` unless created via a developer token.", + "example": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_org": { + "description": "Org of the principal that created this user (`org_...`). `null` on legacy rows.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_team": { + "description": "Team that created this user (`tem_...`). `null` unless created as a team.", + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_user": { + "description": "User who created this account (`usr_...`). `null` on self-signup or legacy rows.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "email": { "description": "Email address of the user.", "example": "user@example.com", + "nullable": true, "type": "string" }, "id": { @@ -57258,31 +62975,43 @@ "name": { "description": "Full display name of the user. `null` if the user has not set a name.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "description": "ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_name": { "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.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_role": { "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.", "example": "member", + "nullable": true, + "type": "string" + }, + "org_slug": { + "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.", + "example": "example-slug", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "sandbox_name": { "description": "Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.", "example": "Example Name", + "nullable": true, "type": "string" } }, @@ -57520,7 +63249,7 @@ ] }, "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", - "created_at": "2024-01-01T00:00:00Z", + "created_at": "string", "default_model": "claude-3-7-sonnet-latest", "description": "An example description.", "email": "user@example.com", @@ -57668,9 +63397,10 @@ }, "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "template_upgrade_available": true, - "updated_at": "2024-01-01T00:00:00Z", + "updated_at": "string", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" }, + "nullable": true, "properties": { "acl": { "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.", @@ -57702,6 +63432,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -57852,23 +63583,25 @@ }, "created_at": { "description": "When the agent was created (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "default_model": { "description": "Default LLM model identifier used by this agent when no model is specified at runtime (e.g. `\"claude-3-7-sonnet-latest\"`).", "example": "claude-3-7-sonnet-latest", + "nullable": true, "type": "string" }, "description": { "description": "Human-readable description of what the agent does. `null` if not set.", "example": "An example description.", + "nullable": true, "type": "string" }, "email": { "description": "Email address provisioned for this agent. `null` if email delivery is not configured.", "example": "user@example.com", + "nullable": true, "type": "string" }, "id": { @@ -57879,16 +63612,19 @@ "identity": { "description": "System-level identity prompt that shapes the agent's persona and behavior.", "example": "You are a helpful assistant that answers questions about ArchAstro products.", + "nullable": true, "type": "string" }, "last_applied_template_config": { "description": "ID of the AgentTemplate config (`cfg_...`) this agent was last provisioned or updated from. `null` for manually created agents.", "example": "cfg_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "lookup_key": { "description": "Stable, user-defined identifier for this agent within the application. Unique per app.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -57906,26 +63642,31 @@ "org": { "description": "ID of the organization this agent belongs to (`org_...`). `null` if the agent is not org-scoped.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_name": { "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.", "example": "Example Name", + "nullable": true, "type": "string" }, "originator": { "description": "Free-form label identifying the source or author that created this agent (e.g. a username or pipeline name).", "example": "deploy-pipeline", + "nullable": true, "type": "string" }, "phone_number": { "description": "Phone number provisioned for this agent. `null` if SMS is not configured.", "example": "+15555550123", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the sandbox environment this agent is scoped to (`dsb_...`). `null` in production deployments.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "source_solution": { @@ -58059,6 +63800,7 @@ "virtual_path": "string" } }, + "nullable": true, "properties": { "current_solution": { "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.", @@ -58133,13 +63875,13 @@ }, "created_at": { "description": "When the Solution config was first imported (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "events": { @@ -58155,6 +63897,7 @@ "image_url": { "description": "Absolute URL of the Solution's cover image — the bundled asset the body's `image:` field names. A stable, non-expiring capability URL (like `org_logo.url`), safe to hold in caches and OpenGraph tags; it 404s if the Solution stops declaring a cover. `null` when the Solution has no cover image, and always `null` for org-scoped rows — the permanent URL is minted for system-scope (catalog) Solutions only.", "example": "https://example.com", + "nullable": true, "type": "string" }, "kind": { @@ -58165,16 +63908,19 @@ "latest_solution": { "description": "When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "latest_version": { "description": "When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", "example": "1.0.0", + "nullable": true, "type": "string" }, "lookup_key": { "description": "The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -58187,11 +63933,13 @@ "name": { "description": "Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "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.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_logo": { @@ -58205,40 +63953,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -58247,11 +64003,13 @@ "org_name": { "description": "Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_slug": { "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.", "example": "example-slug", + "nullable": true, "type": "string" }, "owners": { @@ -58267,6 +64025,7 @@ "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "screenshot_urls": { @@ -58282,11 +64041,13 @@ "solution_id": { "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.", "example": "01234567-89ab-cdef-0123-456789abcdef", + "nullable": true, "type": "string" }, "solution_version": { "description": "Semver string declared in the Solution body (e.g. `\"1.2.0\"`). `null` when the body does not declare a version.", "example": "1.2.0", + "nullable": true, "type": "string" }, "tag_keys": { @@ -58302,6 +64063,7 @@ "template_kind": { "description": "Wrapped template kind — `\"AgentTemplate\"`, `\"AutomationTemplate\"`, `\"AgentRoutineTemplate\"`, `\"AgentToolTemplate\"`, `\"AgentComputerTemplate\"`, or `\"SolutionTemplateRef\"` for ref-mode bundles.", "example": "AgentTemplate", + "nullable": true, "type": "string" }, "templates": { @@ -58334,6 +64096,7 @@ "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "details": { @@ -58341,6 +64104,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -58365,12 +64129,13 @@ }, "properties": { "automation_type": { - "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`).", + "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", "example": "string", + "nullable": true, "type": "string" }, "invoke_contract": { - "description": "Schema-driven payload and participant inputs for an invoked automation. Used by installation clients to collect locked prefills before provisioning.", + "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.", "example": { "input_schema": {}, "participants": [ @@ -58386,10 +64151,12 @@ "payload": {} } }, + "nullable": true, "properties": { "input_schema": { "description": "JSON Schema validated against the whole invoke payload, from the automation's `input_schema_config`. `null` when none is configured.", "example": {}, + "nullable": true, "type": "object" }, "participants": { @@ -58410,10 +64177,12 @@ "required": true, "type": "agent_user" }, + "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", "example": "An example description.", + "nullable": true, "type": "string" }, "name": { @@ -58439,6 +64208,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -58487,11 +64257,13 @@ "display_name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "id": { "description": "Template config ID (`cfg_...`). `null` for inline-only templates.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "kind": { @@ -58502,21 +64274,25 @@ "lookup_key": { "description": "Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", "example": "string", + "nullable": true, "type": "string" }, "name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "virtual_path": { "description": "Stable virtual path assigned to the template config. `null` when no virtual path was set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -58529,8 +64305,7 @@ }, "updated_at": { "description": "When the Solution config was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "upgrade_available": { @@ -58541,6 +64316,7 @@ "virtual_path": { "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.", "example": "string", + "nullable": true, "type": "string" } }, @@ -58626,13 +64402,13 @@ }, "created_at": { "description": "When the Solution config was first imported (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "events": { @@ -58648,6 +64424,7 @@ "image_url": { "description": "Absolute URL of the Solution's cover image — the bundled asset the body's `image:` field names. A stable, non-expiring capability URL (like `org_logo.url`), safe to hold in caches and OpenGraph tags; it 404s if the Solution stops declaring a cover. `null` when the Solution has no cover image, and always `null` for org-scoped rows — the permanent URL is minted for system-scope (catalog) Solutions only.", "example": "https://example.com", + "nullable": true, "type": "string" }, "kind": { @@ -58658,16 +64435,19 @@ "latest_solution": { "description": "When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "latest_version": { "description": "When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", "example": "1.0.0", + "nullable": true, "type": "string" }, "lookup_key": { "description": "The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -58680,11 +64460,13 @@ "name": { "description": "Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "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.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_logo": { @@ -58698,40 +64480,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -58740,11 +64530,13 @@ "org_name": { "description": "Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_slug": { "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.", "example": "example-slug", + "nullable": true, "type": "string" }, "owners": { @@ -58760,6 +64552,7 @@ "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "screenshot_urls": { @@ -58775,11 +64568,13 @@ "solution_id": { "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.", "example": "01234567-89ab-cdef-0123-456789abcdef", + "nullable": true, "type": "string" }, "solution_version": { "description": "Semver string declared in the Solution body (e.g. `\"1.2.0\"`). `null` when the body does not declare a version.", "example": "1.2.0", + "nullable": true, "type": "string" }, "tag_keys": { @@ -58795,6 +64590,7 @@ "template_kind": { "description": "Wrapped template kind — `\"AgentTemplate\"`, `\"AutomationTemplate\"`, `\"AgentRoutineTemplate\"`, `\"AgentToolTemplate\"`, `\"AgentComputerTemplate\"`, or `\"SolutionTemplateRef\"` for ref-mode bundles.", "example": "AgentTemplate", + "nullable": true, "type": "string" }, "templates": { @@ -58827,6 +64623,7 @@ "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "details": { @@ -58834,6 +64631,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -58858,12 +64656,13 @@ }, "properties": { "automation_type": { - "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`).", + "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", "example": "string", + "nullable": true, "type": "string" }, "invoke_contract": { - "description": "Schema-driven payload and participant inputs for an invoked automation. Used by installation clients to collect locked prefills before provisioning.", + "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.", "example": { "input_schema": {}, "participants": [ @@ -58879,10 +64678,12 @@ "payload": {} } }, + "nullable": true, "properties": { "input_schema": { "description": "JSON Schema validated against the whole invoke payload, from the automation's `input_schema_config`. `null` when none is configured.", "example": {}, + "nullable": true, "type": "object" }, "participants": { @@ -58903,10 +64704,12 @@ "required": true, "type": "agent_user" }, + "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", "example": "An example description.", + "nullable": true, "type": "string" }, "name": { @@ -58932,6 +64735,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -58980,11 +64784,13 @@ "display_name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "id": { "description": "Template config ID (`cfg_...`). `null` for inline-only templates.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "kind": { @@ -58995,21 +64801,25 @@ "lookup_key": { "description": "Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", "example": "string", + "nullable": true, "type": "string" }, "name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "virtual_path": { "description": "Stable virtual path assigned to the template config. `null` when no virtual path was set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -59022,8 +64832,7 @@ }, "updated_at": { "description": "When the Solution config was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "upgrade_available": { @@ -59034,6 +64843,7 @@ "virtual_path": { "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.", "example": "string", + "nullable": true, "type": "string" } }, @@ -59069,11 +64879,13 @@ "description": { "description": "Description of the template from the config body. `null` if the current version has no `description` field.", "example": "An example description.", + "nullable": true, "type": "string" }, "display_name": { "description": "Human-readable display name from the config body. `null` if the current version has no `display_name` field.", "example": "Example Name", + "nullable": true, "type": "string" }, "id": { @@ -59089,11 +64901,13 @@ "lookup_key": { "description": "Stable lookup key assigned to this template config. `null` if no lookup key is set.", "example": "string", + "nullable": true, "type": "string" }, "name": { "description": "Template name as stored in the config body. `null` if the current version has no `name` field.", "example": "Example Name", + "nullable": true, "type": "string" }, "updated_at": { @@ -59105,6 +64919,7 @@ "virtual_path": { "description": "Virtual filesystem path for this template config. `null` if not set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -59124,22 +64939,24 @@ "team": { "description": "ID of the team that owns this agent (`tem_...`). `null` if the agent is not team-scoped.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "template_upgrade_available": { "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`).", "example": true, + "nullable": true, "type": "boolean" }, "updated_at": { "description": "When the agent was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "user": { "description": "ID of the user that owns this agent (`usr_...`). `null` if the agent is not user-scoped.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" } }, @@ -59148,16 +64965,19 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "role": { "description": "The authenticated user's membership role in this thread, e.g. `\"owner\"`, `\"member\"`, or `\"viewer\"`. `null` if the user is not a member.", "example": "member", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the developer sandbox this thread is scoped to (`dsb_...`). `null` for production threads.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "settings": { @@ -59167,8 +64987,9 @@ }, "properties": { "agent_enabled": { - "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.", + "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.", "example": true, + "nullable": true, "type": "boolean" } }, @@ -59177,6 +64998,7 @@ "slug": { "description": "URL-safe slug for the thread, used in human-readable permalinks. `null` if not assigned.", "example": "example-slug", + "nullable": true, "type": "string" }, "sub_threads": { @@ -59185,8 +65007,10 @@ {} ], "items": { + "nullable": true, "type": "object" }, + "nullable": true, "type": "array" }, "tags": { @@ -59203,32 +65027,36 @@ "team": { "description": "ID of the team that owns this thread (`team_...`). `null` for user-owned or agent-owned threads.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "title": { "description": "Human-readable name of the thread. `null` if no title has been set.", "example": "Example Title", + "nullable": true, "type": "string" }, "ttl": { - "description": "Time-to-live in seconds after which the thread may be automatically cleaned up. `null` if the thread does not expire.", - "example": 3600, - "type": "integer" + "description": "Offset-free expiry timestamp after which the thread may be automatically cleaned up. `null` if the thread does not expire.", + "example": "2026-08-15T12:00:00", + "nullable": true, + "type": "string" }, "unread_count": { "description": "Number of messages in this thread that the authenticated user has not yet read. Present only when read-state enrichment is requested.", "example": 5, + "nullable": true, "type": "integer" }, "updated_at": { "description": "When the thread was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "user": { "description": "ID of the user who owns this thread (`usr_...`). `null` for team-owned or agent-owned threads.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "visibility": { @@ -59299,6 +65127,7 @@ "description": "An example description.", "is_unlisted": true, "key": "string", + "kind": "personal", "members": [ { "id": "string", @@ -59336,6 +65165,7 @@ "description": "An example description.", "is_unlisted": true, "key": "string", + "kind": "personal", "members": [ { "id": "string", @@ -59380,6 +65210,14 @@ "example": "string", "type": "string" }, + "kind": { + "description": "Optional behavioral subtype. `personal` is accepted only for a user-owned thread and limits membership to that user and agents currently owned by them. Mirror kinds remain server-derived and cannot be selected by callers.", + "enum": [ + "personal" + ], + "example": "personal", + "type": "string" + }, "members": { "description": "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.", "example": [ @@ -59468,8 +65306,9 @@ }, "properties": { "agent_enabled": { - "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.", + "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.", "example": true, + "nullable": true, "type": "boolean" } }, @@ -60728,36 +66567,43 @@ "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -61649,7 +67495,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" } ] @@ -61796,7 +67642,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" } ] @@ -61805,16 +67651,19 @@ "after_cursor": { "description": "Opaque cursor to pass as `after` to retrieve the page of messages newer than this result set. `null` when there are no later messages.", "example": "string", + "nullable": true, "type": "string" }, "anchor": { "description": "Message ID used as the anchor for a windowed query. `null` for ordinary cursor pagination.", "example": "string", + "nullable": true, "type": "string" }, "before_cursor": { "description": "Opaque cursor to pass as `before` to retrieve the page of messages older than this result set. `null` when there are no earlier messages.", "example": "string", + "nullable": true, "type": "string" }, "messages": { @@ -61953,7 +67802,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" } ], @@ -62060,7 +67909,7 @@ ], "branched_thread": "string", "content": "Hello, how can I help you today?", - "created_at": "2024-01-01T00:00:00Z", + "created_at": "string", "has_replies": true, "id": "msg_0aBcDeFgHiJkLmNoPqRsTu", "idempotency_key": "01234567-89ab-cdef-0123-456789abcdef", @@ -62219,7 +68068,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "root_message_id": "string", @@ -62227,7 +68076,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "properties": { @@ -62261,6 +68110,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -62442,16 +68292,19 @@ "alias": { "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", "example": "alice", + "nullable": true, "type": "string" }, "id": { "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "nullable": true, "type": "string" }, "name": { "description": "Display name of the actor shown in the UI. `null` if no name is set.", "example": "Example Name", + "nullable": true, "type": "string" }, "profile_picture": { @@ -62465,40 +68318,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -62512,6 +68373,7 @@ "agent": { "description": "ID of the agent user that sent this message (`agi_...`). `null` for messages sent by human users.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "agent_mode": { @@ -62521,6 +68383,7 @@ "embedded" ], "example": "cli", + "nullable": true, "type": "string" }, "attachments": { @@ -62633,21 +68496,25 @@ "content_type": { "description": "MIME type of the attached file, e.g. `\"image/png\"` or `\"application/pdf\"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.", "example": "application/json", + "nullable": true, "type": "string" }, "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "filename": { "description": "Original filename of the attached file, e.g. `\"report.pdf\"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.", "example": "string", + "nullable": true, "type": "string" }, "height": { "description": "Height in pixels of the media item. Present on `media` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "id": { @@ -62658,6 +68525,7 @@ "image_height": { "description": "Height in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "image_source": { @@ -62671,40 +68539,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -62713,31 +68589,35 @@ "image_url": { "description": "URL of the preview image extracted from the scraped page. Present on `scraped_link` type only. `null` otherwise.", "example": "https://example.com", + "nullable": true, "type": "string" }, "image_width": { "description": "Width in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "media_type": { - "description": "The media category, e.g. `\"video\"` or `\"audio\"`. Present on `media` type only. `null` otherwise.", + "description": "The media category, e.g. `\"video\"` or `\"audio\"`. Present on `media` type only; omitted otherwise.", "example": "application/json", "type": "string" }, "name": { "description": "Display name of the media item. Present on `media` type only. `null` otherwise.", "example": "Example Name", + "nullable": true, "type": "string" }, "object": { - "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`. `null` on other types.", + "description": "The full embedded object payload. For `task` type, contains the task record. For `action` type, contains the action definition. For `chart` type, contains the chart with its inline `spec`. Omitted on other types.", "example": {}, "type": "object" }, "title": { "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.", "example": "Example Title", + "nullable": true, "type": "string" }, "type": { @@ -62748,10 +68628,11 @@ "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "variants": { - "description": "Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only. `null` otherwise.", + "description": "Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only; omitted otherwise.", "example": [ { "content_type": "application/json", @@ -62802,6 +68683,7 @@ "content_type": { "description": "MIME type of this variant's file (e.g., `\"image/jpeg\"`, `\"video/mp4\"`). `null` if the file is not loaded.", "example": "application/json", + "nullable": true, "type": "string" }, "created_at": { @@ -62818,11 +68700,13 @@ "filename": { "description": "Original filename of the uploaded file for this variant. `null` if the file is not loaded.", "example": "string", + "nullable": true, "type": "string" }, "height": { "description": "Height of this variant in pixels. `null` if not recorded.", "example": 600, + "nullable": true, "type": "integer" }, "id": { @@ -62841,40 +68725,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -62889,6 +68781,7 @@ "url": { "description": "Signed download URL for this variant, resolved at request time. `null` if the file is unavailable.", "example": "https://example.com", + "nullable": true, "type": "string" }, "variant_key": { @@ -62899,6 +68792,7 @@ "width": { "description": "Width of this variant in pixels. `null` if not recorded.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -62912,11 +68806,13 @@ "version": { "description": "Version number of the attached artifact at the time of attachment. Present on `artifact` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "width": { "description": "Width in pixels of the media item. Present on `media` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" } }, @@ -62931,17 +68827,18 @@ "branched_thread": { "description": "ID of the thread that was branched from this message (`thr_...`). `null` if this message has not spawned a branch thread.", "example": "string", + "nullable": true, "type": "string" }, "content": { "description": "Text content of the message. `null` for messages that contain only attachments.", "example": "Hello, how can I help you today?", + "nullable": true, "type": "string" }, "created_at": { "description": "When the message was posted (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "has_replies": { @@ -62957,6 +68854,7 @@ "idempotency_key": { "description": "Client-supplied idempotency key used to deduplicate message sends. `null` if the sender did not provide one.", "example": "01234567-89ab-cdef-0123-456789abcdef", + "nullable": true, "type": "string" }, "is_deleted": { @@ -62967,6 +68865,7 @@ "legacy_agent": { "description": "Identifier of the legacy chat agent that sent this message, if applicable. `null` for messages sent by users or modern agent users.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -62979,6 +68878,7 @@ "org": { "description": "ID of the organization that owns this message (`org_...`).", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "reactions": { @@ -63030,6 +68930,7 @@ "rendering_mode": { "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.", "example": "reply", + "nullable": true, "type": "string" }, "replies": { @@ -63045,11 +68946,13 @@ "replies_after_cursor": { "description": "Opaque pagination cursor to fetch replies posted after the current page. Only present when inline replies are included in the response.", "example": "string", + "nullable": true, "type": "string" }, "replies_before_cursor": { "description": "Opaque pagination cursor to fetch replies posted before the current page. Only present when inline replies are included in the response.", "example": "string", + "nullable": true, "type": "string" }, "reply_count": { @@ -63192,9 +69095,10 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, + "nullable": true, "type": "object" }, "root_message_id": { @@ -63206,27 +69110,180 @@ "sandbox": { "description": "ID of the developer sandbox this message belongs to (`dsb_...`). `null` for non-sandbox messages.", "example": "string", + "nullable": true, "type": "string" }, "team": { "description": "ID of the team this message is scoped to (`tem_...`). `null` if the message is not team-scoped.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "thread": { - "description": "ID of the thread this message belongs to (`thr_...`). `null` for messages not yet associated with a thread.", + "description": "ID of the thread this message belongs to (`thr_...`).", "example": "string", "type": "string" }, "type": { "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.", "example": "note", + "nullable": true, "type": "string" }, "user": { "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.", - "example": "string", - "type": "string" + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "oneOf": [ + { + "type": "string" + }, + { + "description": "A platform user account. Represents a human or system actor that can own threads, belong to an organization, and interact with the API.", + "example": { + "alias": "jdoe", + "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "email": "user@example.com", + "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "is_system_user": true, + "metadata": { + "key": "value" + }, + "name": "Example Name", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "org_name": "Example Name", + "org_role": "member", + "org_slug": "example-slug", + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "sandbox_name": "Example Name" + }, + "properties": { + "alias": { + "description": "Short handle or alias for the user. `null` if not set.", + "example": "jdoe", + "nullable": true, + "type": "string" + }, + "app": { + "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.", + "example": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "app_name": { + "description": "Display name of the user's app. `null` when the app association was not preloaded by the caller.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "created_by_agent_user": { + "description": "Agent user that created this account (`usr_...`). `null` unless an agent created it.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_developer": { + "description": "Developer account that created this user (`dva_...`). `null` unless created via a developer token.", + "example": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_org": { + "description": "Org of the principal that created this user (`org_...`). `null` on legacy rows.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_team": { + "description": "Team that created this user (`tem_...`). `null` unless created as a team.", + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_user": { + "description": "User who created this account (`usr_...`). `null` on self-signup or legacy rows.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "email": { + "description": "Email address of the user.", + "example": "user@example.com", + "nullable": true, + "type": "string" + }, + "id": { + "description": "User ID (`usr_...`).", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "is_system_user": { + "description": "`true` if this account is an internal system user rather than a human. System users are created automatically by the platform.", + "example": true, + "type": "boolean" + }, + "metadata": { + "description": "Arbitrary key-value metadata attached to the user. Defaults to an empty object.", + "example": { + "key": "value" + }, + "type": "object" + }, + "name": { + "description": "Full display name of the user. `null` if the user has not set a name.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "org": { + "description": "ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "org_name": { + "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.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "org_role": { + "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.", + "example": "member", + "nullable": true, + "type": "string" + }, + "org_slug": { + "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.", + "example": "example-slug", + "nullable": true, + "type": "string" + }, + "sandbox": { + "description": "ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.", + "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "sandbox_name": { + "description": "Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.", + "example": "Example Name", + "nullable": true, + "type": "string" + } + }, + "required": [ + "id" + ], + "type": "object" + } + ] }, "visibility": { "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.", @@ -63976,7 +70033,7 @@ }, "/api/v1/threads/{thread}/trajectories": { "get": { - "description": "Returns a cursor-paginated list of thread message trajectories associated with the\nspecified thread. Each trajectory links a user message and its agent response to the\nunderlying AI trajectory record that captured the model's reasoning steps.\n\nThe authenticated user must own the thread or be a member of the workspace it belongs\nto. Results are returned in reverse chronological order by default. Use `before_cursor`\nand `after_cursor` to navigate pages; provide at most one cursor per request.\n\nOptionally filter results to trajectories produced in response to a specific message\nby supplying the `message` parameter. When no trajectories match the query, `data`\nis an empty array and both cursor fields are `null`.\n", + "description": "Returns a cursor-paginated list of thread message trajectories associated with the\nspecified thread. Each trajectory links a user message and its agent response to the\nunderlying AI trajectory record that captured the model's reasoning steps.\n\nThe authenticated user must own the thread or be a member of the workspace it belongs\nto. Results are returned in reverse chronological order by default. Use `before_cursor`\nand `after_cursor` to navigate pages; provide at most one cursor per request.\n\nOptionally filter results to trajectories produced in response to a specific message\nby supplying the `message` parameter. When no trajectories match the query, `data`\nis an empty array and both cursor fields are `null`. A cursor that cannot be decoded\nreturns a 400 `invalid_cursor` error.\n", "operationId": "get_api_v1_threads__thread_trajectories", "parameters": [ { @@ -64057,11 +70114,13 @@ "after_cursor": { "description": "Opaque cursor to pass as `after_cursor` to retrieve the next page. `null` when no further pages exist.", "example": "string", + "nullable": true, "type": "string" }, "before_cursor": { "description": "Opaque cursor to pass as `before_cursor` to retrieve the previous page. `null` when this is the first page.", "example": "string", + "nullable": true, "type": "string" }, "data": { @@ -64083,25 +70142,25 @@ "description": "Links a pair of thread messages (user turn and agent reply) to the AI trajectory that produced the response, enabling replay and debugging of model interactions.", "example": { "agent_message": "msg_0aBcDeFgHiJkLmNoPqRsTu", - "created_at": "2024-01-01T00:00:00Z", + "created_at": "string", "id": "tmt_0aBcDeFgHiJkLmNoPqRsTu", "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "thread": "thr_0aBcDeFgHiJkLmNoPqRsTu", "trajectory": "trj_0aBcDeFgHiJkLmNoPqRsTu", - "updated_at": "2024-01-01T00:00:00Z", + "updated_at": "string", "user_message": "msg_0aBcDeFgHiJkLmNoPqRsTu" }, "properties": { "agent_message": { "description": "ID of the agent-authored reply message (`msg_...`). `null` if the trajectory has not yet produced a response message.", "example": "msg_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "created_at": { "description": "When this trajectory link was created (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "id": { @@ -64112,11 +70171,13 @@ "org": { "description": "ID of the organization this trajectory belongs to (`org_...`).", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the sandbox environment in which this trajectory was produced (`dsb_...`). `null` in production contexts.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "thread": { @@ -64131,13 +70192,13 @@ }, "updated_at": { "description": "When this trajectory link was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "user_message": { "description": "ID of the user-authored message that triggered the agent response (`msg_...`). `null` if the agent turn was not preceded by a user message.", "example": "msg_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" } }, @@ -64158,6 +70219,9 @@ }, "description": "Successful response" }, + "400": { + "description": "Invalid cursor" + }, "401": { "description": "Unauthorized" }, @@ -64287,7 +70351,11 @@ "summary": "Retrieve the current user", "x-auth": [ "publishable_key", - "bearer" + "bearer", + "device_flow" + ], + "x-required-scopes": [ + "profile" ] } }, @@ -64511,36 +70579,43 @@ "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -64763,19 +70838,6 @@ "slug": "example-slug", "status": "active", "updated_at": "2024-01-01T00:00:00Z", - "vendor": { - "id": "org_0aBcDeFgHiJkLmNoPqRsTu", - "logo": { - "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", - "height": 600, - "media": "med_0aBcDeFgHiJkLmNoPqRsTu", - "mime_type": "application/json", - "refresh_url": "https://example.com", - "url": "https://example.com", - "width": 800 - }, - "name": "Example Name" - }, "website": "https://example.com" } ] @@ -64800,19 +70862,6 @@ "slug": "example-slug", "status": "active", "updated_at": "2024-01-01T00:00:00Z", - "vendor": { - "id": "org_0aBcDeFgHiJkLmNoPqRsTu", - "logo": { - "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", - "height": 600, - "media": "med_0aBcDeFgHiJkLmNoPqRsTu", - "mime_type": "application/json", - "refresh_url": "https://example.com", - "url": "https://example.com", - "width": 800 - }, - "name": "Example Name" - }, "website": "https://example.com" } ], @@ -64834,19 +70883,6 @@ "slug": "example-slug", "status": "active", "updated_at": "2024-01-01T00:00:00Z", - "vendor": { - "id": "org_0aBcDeFgHiJkLmNoPqRsTu", - "logo": { - "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", - "height": 600, - "media": "med_0aBcDeFgHiJkLmNoPqRsTu", - "mime_type": "application/json", - "refresh_url": "https://example.com", - "url": "https://example.com", - "width": 800 - }, - "name": "Example Name" - }, "website": "https://example.com" }, "properties": { @@ -64882,7 +70918,7 @@ "type": "string" }, "onboarding_solution_lookup_key": { - "description": "Lookup key (`sol-...`) of the Solution that drove this org's customer onboarding, stamped when the org was first linked into a vendor's network via an explore-install. `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.", + "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.", "example": "string", "type": "string" }, @@ -64922,88 +70958,6 @@ "format": "date-time", "type": "string" }, - "vendor": { - "description": "Branding of the solution vendor whose network this organization belongs to — the vendor of the oldest active vendor relationship. Only present for organizations on the `\"customer\"` onboarding track; `null` for vendor-track organizations (including vendors that later joined another vendor's network) and for customers with no active vendor link. Clients use it to co-brand the workspace (\"ArchAgents by Acme\").", - "example": { - "id": "org_0aBcDeFgHiJkLmNoPqRsTu", - "logo": { - "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", - "height": 600, - "media": "med_0aBcDeFgHiJkLmNoPqRsTu", - "mime_type": "application/json", - "refresh_url": "https://example.com", - "url": "https://example.com", - "width": 800 - }, - "name": "Example Name" - }, - "properties": { - "id": { - "description": "Organization ID of the vendor (`org_...`).", - "example": "org_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "logo": { - "description": "Logo of the vendor organization. The `url` is a stable, non-expiring capability URL served by the platform (the same mechanism as catalog `org_logo` fields), safe to hold in caches; `refresh_url` is `null`. `null` when the vendor has no logo.", - "example": { - "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", - "height": 600, - "media": "med_0aBcDeFgHiJkLmNoPqRsTu", - "mime_type": "application/json", - "refresh_url": "https://example.com", - "url": "https://example.com", - "width": 800 - }, - "properties": { - "file": { - "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", - "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "height": { - "description": "Height of the image in pixels. `null` if not known.", - "example": 600, - "type": "integer" - }, - "media": { - "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", - "example": "med_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "mime_type": { - "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", - "example": "application/json", - "type": "string" - }, - "refresh_url": { - "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.", - "example": "https://example.com", - "type": "string" - }, - "url": { - "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.", - "example": "https://example.com", - "type": "string" - }, - "width": { - "description": "Width of the image in pixels. `null` if not known.", - "example": 800, - "type": "integer" - } - }, - "type": "object" - }, - "name": { - "description": "Display name of the vendor organization. `null` if the vendor has not set a name.", - "example": "Example Name", - "type": "string" - } - }, - "required": [ - "id" - ], - "type": "object" - }, "website": { "description": "Public website URL for the organization. `null` if not set.", "example": "https://example.com", @@ -65241,6 +71195,46 @@ "type": "string" } }, + { + "description": "Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_id`.", + "example": "string", + "in": "query", + "name": "source_scope", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Return only tasks whose source matches this object kind. Must be supplied with the other source filters.", + "example": "string", + "in": "query", + "name": "source_type", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Return only tasks whose source matches this object identity. Must be supplied with the other source filters.", + "example": "string", + "in": "query", + "name": "source_id", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Return only tasks with this exact epic label.", + "example": "string", + "in": "query", + "name": "epic", + "required": false, + "schema": { + "type": "string" + } + }, { "description": "Restrict results to tasks whose name or description contains this string.", "example": "string", @@ -65301,6 +71295,16 @@ "type": "boolean" } }, + { + "description": "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.", + "example": true, + "in": "query", + "name": "ready", + "required": false, + "schema": { + "type": "boolean" + } + }, { "description": "Maximum number of tasks to return. Capped at 100.", "example": 1, @@ -65361,6 +71365,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -65390,6 +71395,9 @@ "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "priority": 2, "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", "status": "open", "subtasks_count": 1, "tags": [ @@ -65406,10 +71414,12 @@ "properties": { "after_cursor": { "example": "string", + "nullable": true, "type": "string" }, "before_cursor": { "example": "string", + "nullable": true, "type": "string" }, "data": { @@ -65444,6 +71454,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -65473,6 +71484,9 @@ "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "priority": 2, "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", "status": "open", "subtasks_count": 1, "tags": [ @@ -65515,6 +71529,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -65544,6 +71559,9 @@ "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "priority": 2, "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", "status": "open", "subtasks_count": 1, "tags": [ @@ -65558,6 +71576,7 @@ "agent": { "description": "ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "blocked_by_count": { @@ -65569,21 +71588,218 @@ "description": "When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", "example": "2024-01-01T00:00:00Z", "format": "date-time", + "nullable": true, "type": "string" }, - "comments_count": { - "description": "Total number of comments posted on this task.", - "example": 1, - "type": "integer" + "comments_count": { + "description": "Total number of comments posted on this task.", + "example": 1, + "type": "integer" + }, + "created_at": { + "description": "When the task was created (ISO 8601).", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "type": "string" + }, + "created_by_actor": { + "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).", + "example": { + "alias": "alice", + "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "name": "Example Name", + "profile_picture": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + } + }, + "nullable": true, + "properties": { + "alias": { + "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", + "example": "alice", + "nullable": true, + "type": "string" + }, + "id": { + "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", + "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "nullable": true, + "type": "string" + }, + "name": { + "description": "Display name of the actor shown in the UI. `null` if no name is set.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "profile_picture": { + "description": "Profile picture for the actor. `null` if the actor has no profile picture.", + "example": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + }, + "nullable": true, + "properties": { + "file": { + "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", + "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "height": { + "description": "Height of the image in pixels. `null` if not known.", + "example": 600, + "nullable": true, + "type": "integer" + }, + "media": { + "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", + "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "mime_type": { + "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", + "example": "application/json", + "nullable": true, + "type": "string" + }, + "refresh_url": { + "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.", + "example": "https://example.com", + "nullable": true, + "type": "string" + }, + "url": { + "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.", + "example": "https://example.com", + "nullable": true, + "type": "string" + }, + "width": { + "description": "Width of the image in pixels. `null` if not known.", + "example": 800, + "nullable": true, + "type": "integer" + } + }, + "type": "object" + } + }, + "type": "object" + }, + "created_by_agent": { + "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.", + "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_user": { + "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.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "current_lease": { + "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.", + "example": { + "expires_at": "2024-01-01T00:00:00Z", + "harness": "string", + "session_name": "Example Name" + }, + "nullable": true, + "properties": { + "expires_at": { + "description": "Server-calculated lease expiry in ISO 8601 format.", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "type": "string" + }, + "harness": { + "description": "Bounded harness identifier for the coding session.", + "example": "string", + "type": "string" + }, + "session_name": { + "description": "Display name supplied by the coding session that holds the lease.", + "example": "Example Name", + "type": "string" + } + }, + "required": [ + "session_name", + "harness", + "expires_at" + ], + "type": "object" + }, + "description": { + "description": "Long-form description or notes for the task. `null` if no description has been provided.", + "example": "An example description.", + "nullable": true, + "type": "string" + }, + "due_date": { + "description": "Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "nullable": true, + "type": "string" + }, + "epic": { + "description": "Free-form grouping label. `null` when the task is not in an epic.", + "example": "string", + "nullable": true, + "type": "string" + }, + "id": { + "description": "Task ID (`tsk_...`).", + "example": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "is_blocked": { + "description": "`true` while at least one blocking task is not yet done. Informational only — a blocked task can still change status — and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on list/show reads; create/update responses report `false` until the next read.", + "example": true, + "type": "boolean" + }, + "links": { + "description": "Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.", + "example": { + "key": "value" + }, + "type": "object" + }, + "metadata": { + "description": "Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.", + "example": { + "key": "value" + }, + "type": "object" + }, + "name": { + "description": "Human-readable title of the task.", + "example": "Example Name", + "type": "string" }, - "created_at": { - "description": "When the task was created (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "org": { + "description": "ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, - "created_by_actor": { - "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).", + "owner_actor": { + "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).", "example": { "alias": "alice", "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", @@ -65598,20 +71814,24 @@ "width": 800 } }, + "nullable": true, "properties": { "alias": { "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", "example": "alice", + "nullable": true, "type": "string" }, "id": { "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "nullable": true, "type": "string" }, "name": { "description": "Display name of the actor shown in the UI. `null` if no name is set.", "example": "Example Name", + "nullable": true, "type": "string" }, "profile_picture": { @@ -65625,40 +71845,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -65667,97 +71895,475 @@ }, "type": "object" }, - "created_by_agent": { - "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.", + "owner_agent": { + "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.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, - "created_by_user": { - "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.", + "owner_user": { + "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.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, - "current_lease": { - "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.", - "example": { - "expires_at": "2024-01-01T00:00:00Z", - "harness": "string", - "session_name": "Example Name" - }, + "parent": { + "description": "ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks. Subtasks nest exactly one level.", + "example": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "nullable": true, - "properties": { - "expires_at": { - "description": "Server-calculated lease expiry in ISO 8601 format.", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", - "type": "string" - }, - "harness": { - "description": "Bounded harness identifier for the coding session.", - "example": "string", - "type": "string" - }, - "session_name": { - "description": "Display name supplied by the coding session that holds the lease.", - "example": "Example Name", - "type": "string" - } - }, - "required": [ - "session_name", - "harness", - "expires_at" - ], - "type": "object" + "type": "string" }, - "description": { - "description": "Long-form description or notes for the task. `null` if no description has been provided.", - "example": "An example description.", + "priority": { + "description": "Priority level of the task from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when not explicitly set.", + "example": 2, + "type": "integer" + }, + "sandbox": { + "description": "ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", + "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, - "due_date": { - "description": "Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "source_id": { + "description": "Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", + "example": "string", + "nullable": true, "type": "string" }, - "id": { - "description": "Task ID (`tsk_...`).", - "example": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "source_scope": { + "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`.", + "example": "string", + "nullable": true, "type": "string" }, - "is_blocked": { - "description": "`true` while at least one blocking task is not yet done. Informational only — a blocked task can still change status — and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on list/show reads; create/update responses report `false` until the next read.", - "example": true, - "type": "boolean" + "source_type": { + "description": "Kind of source object (for example `repository`). `null` when the task has no source.", + "example": "string", + "nullable": true, + "type": "string" }, - "links": { - "description": "Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.", - "example": { - "key": "value" - }, - "type": "object" + "status": { + "description": "Current status of the task. One of `\"open\"`, `\"in_progress\"`, or `\"done\"`.", + "example": "open", + "type": "string" }, - "metadata": { - "description": "Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.", - "example": { - "key": "value" + "subtasks_count": { + "description": "Number of subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.", + "example": 1, + "type": "integer" + }, + "tags": { + "description": "Labels for grouping and filtering, stored lowercase and de-duplicated. Empty array when untagged.", + "example": [ + "string" + ], + "items": { + "type": "string" }, - "type": "object" + "type": "array" }, - "name": { - "description": "Human-readable title of the task.", - "example": "Example Name", + "team": { + "description": "ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, - "org": { - "description": "ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", - "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "thread": { + "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.", + "example": "thr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, - "owner_actor": { - "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).", - "example": { + "updated_at": { + "description": "When the task was last modified (ISO 8601).", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "type": "string" + }, + "user": { + "description": "ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + } + }, + "required": [ + "id", + "name", + "status" + ], + "type": "object" + }, + "type": "array" + }, + "has_more": { + "example": true, + "type": "boolean" + } + }, + "required": [ + "data", + "has_more" + ], + "type": "object" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "404": { + "description": "Task owner not found" + }, + "422": { + "description": "Invalid explicit owner or organization context" + } + }, + "summary": "List an owner's tasks", + "x-auth": [ + "publishable_key", + "bearer" + ] + }, + "post": { + "description": "Creates a new task owned by the specified user or team and returns the full\ntask object. User-authenticated calls are attributed to the authenticated\nuser or agent. App-scoped developer and server-to-server callers must provide\nthe task's explicit `org` scope and an explicit `user` or `agent` actor for\nteam tasks; a user-owned task reuses the user in the route unless an explicit\nagent is supplied. Every referenced principal is validated against the app,\nowner, and team membership before creation.\n", + "operationId": "post_api_v1_users__user_tasks", + "parameters": [ + { + "description": "User ID (`usr_...`). On a user route this is the task owner and creator; on a team route it is the explicit acting user for a developer or server-to-server call.", + "example": "string", + "in": "path", + "name": "user", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "example": { + "agent": "string", + "org": "string", + "task": { + "description": "An example description.", + "due_date": "2024-01-01T00:00:00Z", + "epic": "billing-cadence", + "links": { + "key": "value" + }, + "metadata": { + "key": "value" + }, + "name": "Example Name", + "owner_agent": "string", + "owner_user": "string", + "parent": "tsk_01j3k5m7n9p2r4s6t8v0w1x2", + "priority": 2, + "source_id": "ArchAstro/firstlanding", + "source_scope": "github.com", + "source_type": "repository", + "status": "open", + "tags": [ + "backend", + "q3-launch" + ], + "thread": "thr_01j3k5m7n9p2r4s6t8v0w1x2" + }, + "team": "string" + }, + "properties": { + "agent": { + "description": "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.", + "example": "string", + "type": "string" + }, + "org": { + "description": "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.", + "example": "string", + "type": "string" + }, + "task": { + "description": "Attributes for the task to create. `name` is required; all other fields are optional.", + "example": { + "description": "An example description.", + "due_date": "2024-01-01T00:00:00Z", + "epic": "billing-cadence", + "links": { + "key": "value" + }, + "metadata": { + "key": "value" + }, + "name": "Example Name", + "owner_agent": "string", + "owner_user": "string", + "parent": "tsk_01j3k5m7n9p2r4s6t8v0w1x2", + "priority": 2, + "source_id": "ArchAstro/firstlanding", + "source_scope": "github.com", + "source_type": "repository", + "status": "open", + "tags": [ + "backend", + "q3-launch" + ], + "thread": "thr_01j3k5m7n9p2r4s6t8v0w1x2" + }, + "properties": { + "description": { + "description": "Optional long-form description or notes for the task. Supports plain text.", + "example": "An example description.", + "type": "string" + }, + "due_date": { + "description": "Date and time by which the task should be completed (ISO 8601). Omit to create the task without a due date.", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "type": "string" + }, + "epic": { + "description": "Optional free-form grouping label.", + "example": "billing-cadence", + "type": "string" + }, + "links": { + "description": "Arbitrary key-value map of named URLs or references associated with the task (e.g. external ticket links).", + "example": { + "key": "value" + }, + "type": "object" + }, + "metadata": { + "description": "Arbitrary key-value map for storing application-specific data alongside the task. Omit to create the task with no metadata.", + "example": { + "key": "value" + }, + "type": "object" + }, + "name": { + "description": "Human-readable title for the task.", + "example": "Example Name", + "type": "string" + }, + "owner_agent": { + "description": "ID of the agent to assign as owner (`agi_...`). Mutually exclusive with `owner_user`; omit to leave the task unassigned.", + "example": "string", + "type": "string" + }, + "owner_user": { + "description": "ID of the user to assign as owner (`usr_...`). Mutually exclusive with `owner_agent`; omit to leave the task unassigned.", + "example": "string", + "type": "string" + }, + "parent": { + "description": "Create this task as a subtask of an existing top-level task (`tsk_...`). Subtasks nest exactly one level.", + "example": "tsk_01j3k5m7n9p2r4s6t8v0w1x2", + "type": "string" + }, + "priority": { + "description": "Priority level from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when omitted.", + "example": 2, + "type": "integer" + }, + "source_id": { + "description": "Source object identity (for example `ArchAstro/firstlanding`).", + "example": "ArchAstro/firstlanding", + "type": "string" + }, + "source_scope": { + "description": "Container of the work this task is about (for example `github.com`). Must be supplied with `source_type` and `source_id`.", + "example": "github.com", + "type": "string" + }, + "source_type": { + "description": "Kind of source object (for example `repository`).", + "example": "repository", + "type": "string" + }, + "status": { + "description": "Initial status for the task. One of `\"open\"`, `\"in_progress\"`, or `\"done\"`. Defaults to `\"open\"` when omitted.", + "example": "open", + "type": "string" + }, + "tags": { + "description": "Labels for grouping and filtering (max 20, each up to 40 characters). Stored canonically: lowercase, trimmed, de-duplicated.", + "example": [ + "backend", + "q3-launch" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "thread": { + "description": "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.", + "example": "thr_01j3k5m7n9p2r4s6t8v0w1x2", + "type": "string" + } + }, + "required": [ + "name" + ], + "type": "object" + }, + "team": { + "description": "Team ID (`tem_...`). The task will be owned by this team.", + "example": "string", + "type": "string" + } + }, + "required": [ + "task" + ], + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Task" + } + } + }, + "description": "The newly created task." + }, + "401": { + "description": "Unauthorized" + }, + "404": { + "description": "Task owner not found" + }, + "422": { + "description": "Validation error" + } + }, + "summary": "Create a task for an owner", + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/users/{user}/tasks/blocker_cycles": { + "get": { + "description": "Runs an on-demand diagnostic over unfinished tasks owned by the specified\nteam or user and returns a forward cursor-paginated page of complete cyclic\nblocker components. Detection is bounded to owners with at most 100\nunfinished tasks. This endpoint is read-only: cycles do not prevent task\nupdates, lease acquisition, or completion.\n", + "operationId": "get_api_v1_users__user_tasks_blocker_cycles", + "parameters": [ + { + "description": "Team ID (`tem_...`) owning the tasks.", + "example": "string", + "in": "query", + "name": "team", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "User ID (`usr_...`) owning the tasks.", + "example": "string", + "in": "path", + "name": "user", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Optional organization context for privileged callers.", + "example": "string", + "in": "query", + "name": "org", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Maximum cycle components to return. Defaults to 50; maximum is 100.", + "example": 1, + "in": "query", + "name": "limit", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "description": "Opaque cursor returned by the preceding page.", + "example": "string", + "in": "query", + "name": "after_cursor", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "description": "On-demand task blocker cycle diagnostics.", + "example": { + "after_cursor": "string", + "before_cursor": "string", + "data": [ + { + "tasks": [ + { + "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "blocked_by_count": 1, + "closed_at": "2024-01-01T00:00:00Z", + "comments_count": 1, + "created_at": "2024-01-01T00:00:00Z", + "created_by_actor": { + "alias": "alice", + "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "name": "Example Name", + "profile_picture": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + } + }, + "created_by_agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "current_lease": { + "expires_at": "2024-01-01T00:00:00Z", + "harness": "string", + "session_name": "Example Name" + }, + "description": "An example description.", + "due_date": "2024-01-01T00:00:00Z", + "epic": "string", + "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "is_blocked": true, + "links": { + "key": "value" + }, + "metadata": { + "key": "value" + }, + "name": "Example Name", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "owner_actor": { "alias": "alice", "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", "name": "Example Name", @@ -65771,25 +72377,166 @@ "width": 800 } }, - "properties": { - "alias": { - "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", - "example": "alice", - "type": "string" + "owner_agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "owner_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "priority": 2, + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", + "status": "open", + "subtasks_count": 1, + "tags": [ + "string" + ], + "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "thread": "thr_0aBcDeFgHiJkLmNoPqRsTu", + "updated_at": "2024-01-01T00:00:00Z", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" + } + ] + } + ], + "has_more": true + }, + "properties": { + "after_cursor": { + "example": "string", + "type": "string" + }, + "before_cursor": { + "example": "string", + "type": "string" + }, + "data": { + "example": [ + { + "tasks": [ + { + "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "blocked_by_count": 1, + "closed_at": "2024-01-01T00:00:00Z", + "comments_count": 1, + "created_at": "2024-01-01T00:00:00Z", + "created_by_actor": { + "alias": "alice", + "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "name": "Example Name", + "profile_picture": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + } }, - "id": { - "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", - "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", - "type": "string" + "created_by_agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "current_lease": { + "expires_at": "2024-01-01T00:00:00Z", + "harness": "string", + "session_name": "Example Name" }, - "name": { - "description": "Display name of the actor shown in the UI. `null` if no name is set.", - "example": "Example Name", - "type": "string" + "description": "An example description.", + "due_date": "2024-01-01T00:00:00Z", + "epic": "string", + "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "is_blocked": true, + "links": { + "key": "value" }, - "profile_picture": { - "description": "Profile picture for the actor. `null` if the actor has no profile picture.", - "example": { + "metadata": { + "key": "value" + }, + "name": "Example Name", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "owner_actor": { + "alias": "alice", + "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "name": "Example Name", + "profile_picture": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + } + }, + "owner_agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "owner_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "priority": 2, + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", + "status": "open", + "subtasks_count": 1, + "tags": [ + "string" + ], + "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "thread": "thr_0aBcDeFgHiJkLmNoPqRsTu", + "updated_at": "2024-01-01T00:00:00Z", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" + } + ] + } + ], + "items": { + "description": "A strongly connected component of unfinished task blocker edges.", + "example": { + "tasks": [ + { + "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "blocked_by_count": 1, + "closed_at": "2024-01-01T00:00:00Z", + "comments_count": 1, + "created_at": "2024-01-01T00:00:00Z", + "created_by_actor": { + "alias": "alice", + "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "name": "Example Name", + "profile_picture": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + } + }, + "created_by_agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "current_lease": { + "expires_at": "2024-01-01T00:00:00Z", + "harness": "string", + "session_name": "Example Name" + }, + "description": "An example description.", + "due_date": "2024-01-01T00:00:00Z", + "epic": "string", + "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "is_blocked": true, + "links": { + "key": "value" + }, + "metadata": { + "key": "value" + }, + "name": "Example Name", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "owner_actor": { + "alias": "alice", + "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "name": "Example Name", + "profile_picture": { "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", "height": 600, "media": "med_0aBcDeFgHiJkLmNoPqRsTu", @@ -65797,120 +72544,606 @@ "refresh_url": "https://example.com", "url": "https://example.com", "width": 800 + } + }, + "owner_agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "owner_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "priority": 2, + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", + "status": "open", + "subtasks_count": 1, + "tags": [ + "string" + ], + "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "thread": "thr_0aBcDeFgHiJkLmNoPqRsTu", + "updated_at": "2024-01-01T00:00:00Z", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" + } + ] + }, + "properties": { + "tasks": { + "description": "Every unfinished task in this cyclic blocker component.", + "example": [ + { + "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "blocked_by_count": 1, + "closed_at": "2024-01-01T00:00:00Z", + "comments_count": 1, + "created_at": "2024-01-01T00:00:00Z", + "created_by_actor": { + "alias": "alice", + "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "name": "Example Name", + "profile_picture": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + } + }, + "created_by_agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "current_lease": { + "expires_at": "2024-01-01T00:00:00Z", + "harness": "string", + "session_name": "Example Name" + }, + "description": "An example description.", + "due_date": "2024-01-01T00:00:00Z", + "epic": "string", + "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "is_blocked": true, + "links": { + "key": "value" + }, + "metadata": { + "key": "value" + }, + "name": "Example Name", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "owner_actor": { + "alias": "alice", + "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "name": "Example Name", + "profile_picture": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + } + }, + "owner_agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "owner_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "priority": 2, + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", + "status": "open", + "subtasks_count": 1, + "tags": [ + "string" + ], + "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "thread": "thr_0aBcDeFgHiJkLmNoPqRsTu", + "updated_at": "2024-01-01T00:00:00Z", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" + } + ], + "items": { + "description": "A task representing a unit of work, optionally assignable to a user or agent.", + "example": { + "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "blocked_by_count": 1, + "closed_at": "2024-01-01T00:00:00Z", + "comments_count": 1, + "created_at": "2024-01-01T00:00:00Z", + "created_by_actor": { + "alias": "alice", + "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "name": "Example Name", + "profile_picture": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + } + }, + "created_by_agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "current_lease": { + "expires_at": "2024-01-01T00:00:00Z", + "harness": "string", + "session_name": "Example Name" + }, + "description": "An example description.", + "due_date": "2024-01-01T00:00:00Z", + "epic": "string", + "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "is_blocked": true, + "links": { + "key": "value" + }, + "metadata": { + "key": "value" + }, + "name": "Example Name", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "owner_actor": { + "alias": "alice", + "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "name": "Example Name", + "profile_picture": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + } + }, + "owner_agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "owner_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "priority": 2, + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", + "status": "open", + "subtasks_count": 1, + "tags": [ + "string" + ], + "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "thread": "thr_0aBcDeFgHiJkLmNoPqRsTu", + "updated_at": "2024-01-01T00:00:00Z", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" + }, + "properties": { + "agent": { + "description": "ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", + "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "blocked_by_count": { + "description": "Number of tasks marked as blocking this task, whether or not they are done (see `GET /tasks/{task}/blockers`). Computed on list/show reads; create/update responses may lag one read behind.", + "example": 1, + "type": "integer" + }, + "closed_at": { + "description": "When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "nullable": true, + "type": "string" + }, + "comments_count": { + "description": "Total number of comments posted on this task.", + "example": 1, + "type": "integer" + }, + "created_at": { + "description": "When the task was created (ISO 8601).", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "type": "string" + }, + "created_by_actor": { + "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).", + "example": { + "alias": "alice", + "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "name": "Example Name", + "profile_picture": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + } + }, + "nullable": true, + "properties": { + "alias": { + "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", + "example": "alice", + "nullable": true, + "type": "string" + }, + "id": { + "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", + "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "nullable": true, + "type": "string" + }, + "name": { + "description": "Display name of the actor shown in the UI. `null` if no name is set.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "profile_picture": { + "description": "Profile picture for the actor. `null` if the actor has no profile picture.", + "example": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + }, + "nullable": true, + "properties": { + "file": { + "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", + "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "height": { + "description": "Height of the image in pixels. `null` if not known.", + "example": 600, + "nullable": true, + "type": "integer" + }, + "media": { + "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", + "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "mime_type": { + "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", + "example": "application/json", + "nullable": true, + "type": "string" + }, + "refresh_url": { + "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.", + "example": "https://example.com", + "nullable": true, + "type": "string" + }, + "url": { + "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.", + "example": "https://example.com", + "nullable": true, + "type": "string" + }, + "width": { + "description": "Width of the image in pixels. `null` if not known.", + "example": 800, + "nullable": true, + "type": "integer" + } + }, + "type": "object" + } + }, + "type": "object" + }, + "created_by_agent": { + "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.", + "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_user": { + "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.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "current_lease": { + "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.", + "example": { + "expires_at": "2024-01-01T00:00:00Z", + "harness": "string", + "session_name": "Example Name" + }, + "nullable": true, + "properties": { + "expires_at": { + "description": "Server-calculated lease expiry in ISO 8601 format.", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "type": "string" + }, + "harness": { + "description": "Bounded harness identifier for the coding session.", + "example": "string", + "type": "string" + }, + "session_name": { + "description": "Display name supplied by the coding session that holds the lease.", + "example": "Example Name", + "type": "string" + } + }, + "required": [ + "session_name", + "harness", + "expires_at" + ], + "type": "object" + }, + "description": { + "description": "Long-form description or notes for the task. `null` if no description has been provided.", + "example": "An example description.", + "nullable": true, + "type": "string" + }, + "due_date": { + "description": "Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "nullable": true, + "type": "string" + }, + "epic": { + "description": "Free-form grouping label. `null` when the task is not in an epic.", + "example": "string", + "nullable": true, + "type": "string" + }, + "id": { + "description": "Task ID (`tsk_...`).", + "example": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "is_blocked": { + "description": "`true` while at least one blocking task is not yet done. Informational only — a blocked task can still change status — and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on list/show reads; create/update responses report `false` until the next read.", + "example": true, + "type": "boolean" }, - "properties": { - "file": { - "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", - "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "height": { - "description": "Height of the image in pixels. `null` if not known.", - "example": 600, - "type": "integer" + "links": { + "description": "Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.", + "example": { + "key": "value" }, - "media": { - "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", - "example": "med_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" + "type": "object" + }, + "metadata": { + "description": "Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.", + "example": { + "key": "value" }, - "mime_type": { - "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", - "example": "application/json", - "type": "string" + "type": "object" + }, + "name": { + "description": "Human-readable title of the task.", + "example": "Example Name", + "type": "string" + }, + "org": { + "description": "ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "owner_actor": { + "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).", + "example": { + "alias": "alice", + "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "name": "Example Name", + "profile_picture": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + } }, - "refresh_url": { - "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.", - "example": "https://example.com", - "type": "string" + "nullable": true, + "properties": { + "alias": { + "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", + "example": "alice", + "nullable": true, + "type": "string" + }, + "id": { + "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", + "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "nullable": true, + "type": "string" + }, + "name": { + "description": "Display name of the actor shown in the UI. `null` if no name is set.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "profile_picture": { + "description": "Profile picture for the actor. `null` if the actor has no profile picture.", + "example": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + }, + "nullable": true, + "properties": { + "file": { + "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", + "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "height": { + "description": "Height of the image in pixels. `null` if not known.", + "example": 600, + "nullable": true, + "type": "integer" + }, + "media": { + "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", + "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "mime_type": { + "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", + "example": "application/json", + "nullable": true, + "type": "string" + }, + "refresh_url": { + "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.", + "example": "https://example.com", + "nullable": true, + "type": "string" + }, + "url": { + "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.", + "example": "https://example.com", + "nullable": true, + "type": "string" + }, + "width": { + "description": "Width of the image in pixels. `null` if not known.", + "example": 800, + "nullable": true, + "type": "integer" + } + }, + "type": "object" + } }, - "url": { - "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.", - "example": "https://example.com", + "type": "object" + }, + "owner_agent": { + "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.", + "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "owner_user": { + "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.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "parent": { + "description": "ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks. Subtasks nest exactly one level.", + "example": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "priority": { + "description": "Priority level of the task from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when not explicitly set.", + "example": 2, + "type": "integer" + }, + "sandbox": { + "description": "ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", + "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "source_id": { + "description": "Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", + "example": "string", + "nullable": true, + "type": "string" + }, + "source_scope": { + "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`.", + "example": "string", + "nullable": true, + "type": "string" + }, + "source_type": { + "description": "Kind of source object (for example `repository`). `null` when the task has no source.", + "example": "string", + "nullable": true, + "type": "string" + }, + "status": { + "description": "Current status of the task. One of `\"open\"`, `\"in_progress\"`, or `\"done\"`.", + "example": "open", + "type": "string" + }, + "subtasks_count": { + "description": "Number of subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.", + "example": 1, + "type": "integer" + }, + "tags": { + "description": "Labels for grouping and filtering, stored lowercase and de-duplicated. Empty array when untagged.", + "example": [ + "string" + ], + "items": { "type": "string" }, - "width": { - "description": "Width of the image in pixels. `null` if not known.", - "example": 800, - "type": "integer" - } + "type": "array" }, - "type": "object" - } - }, - "type": "object" - }, - "owner_agent": { - "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.", - "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "owner_user": { - "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.", - "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "parent": { - "description": "ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks. Subtasks nest exactly one level.", - "example": "tsk_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "priority": { - "description": "Priority level of the task from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when not explicitly set.", - "example": 2, - "type": "integer" - }, - "sandbox": { - "description": "ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", - "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "status": { - "description": "Current status of the task. One of `\"open\"`, `\"in_progress\"`, or `\"done\"`.", - "example": "open", - "type": "string" - }, - "subtasks_count": { - "description": "Number of subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.", - "example": 1, - "type": "integer" - }, - "tags": { - "description": "Labels for grouping and filtering, stored lowercase and de-duplicated. Empty array when untagged.", - "example": [ - "string" - ], - "items": { - "type": "string" + "team": { + "description": "ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "thread": { + "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.", + "example": "thr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "updated_at": { + "description": "When the task was last modified (ISO 8601).", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "type": "string" + }, + "user": { + "description": "ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + } + }, + "required": [ + "id", + "name", + "status" + ], + "type": "object" }, "type": "array" - }, - "team": { - "description": "ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", - "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "thread": { - "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.", - "example": "thr_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "updated_at": { - "description": "When the task was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", - "type": "string" - }, - "user": { - "description": "ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", - "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" } }, "required": [ - "id", - "name", - "status" + "tasks" ], "type": "object" }, @@ -65938,21 +73171,33 @@ "description": "Task owner not found" }, "422": { - "description": "Invalid explicit owner or organization context" + "description": "Invalid owner context or diagnostic limit" } }, - "summary": "List an owner's tasks", + "summary": "List task blocker cycles", "x-auth": [ "publishable_key", "bearer" ] - }, - "post": { - "description": "Creates a new task owned by the specified user or team and returns the full\ntask object. User-authenticated calls are attributed to the authenticated\nuser or agent. App-scoped developer and server-to-server callers must provide\nthe task's explicit `org` scope and an explicit `user` or `agent` actor for\nteam tasks; a user-owned task reuses the user in the route unless an explicit\nagent is supplied. Every referenced principal is validated against the app,\nowner, and team membership before creation.\n", - "operationId": "post_api_v1_users__user_tasks", + } + }, + "/api/v1/users/{user}/tasks/ready": { + "get": { + "description": "Returns open tasks with no unfinished blockers and no active session lease.\nReadiness is calculated by the server from the current task projection. It is\na snapshot, not a reservation; claim a task lease before starting work.\n\nPass `explain=true` to include every open task with a stable readiness reason.\n", + "operationId": "get_api_v1_users__user_tasks_ready", "parameters": [ { - "description": "User ID (`usr_...`). On a user route this is the task owner and creator; on a team route it is the explicit acting user for a developer or server-to-server call.", + "description": "Team ID (`tem_...`) owning the tasks.", + "example": "string", + "in": "query", + "name": "team", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "User ID (`usr_...`) owning the tasks.", "example": "string", "in": "path", "name": "user", @@ -65960,230 +73205,79 @@ "schema": { "type": "string" } - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "example": { - "agent": "string", - "org": "string", - "task": { - "description": "An example description.", - "due_date": "2024-01-01T00:00:00Z", - "links": { - "key": "value" - }, - "metadata": { - "key": "value" - }, - "name": "Example Name", - "owner_agent": "string", - "owner_user": "string", - "parent": "tsk_01j3k5m7n9p2r4s6t8v0w1x2", - "priority": 2, - "status": "open", - "tags": [ - "backend", - "q3-launch" - ], - "thread": "thr_01j3k5m7n9p2r4s6t8v0w1x2" - }, - "team": "string" - }, - "properties": { - "agent": { - "description": "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.", - "example": "string", - "type": "string" - }, - "org": { - "description": "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.", - "example": "string", - "type": "string" - }, - "task": { - "description": "Attributes for the task to create. `name` is required; all other fields are optional.", - "example": { - "description": "An example description.", - "due_date": "2024-01-01T00:00:00Z", - "links": { - "key": "value" - }, - "metadata": { - "key": "value" - }, - "name": "Example Name", - "owner_agent": "string", - "owner_user": "string", - "parent": "tsk_01j3k5m7n9p2r4s6t8v0w1x2", - "priority": 2, - "status": "open", - "tags": [ - "backend", - "q3-launch" - ], - "thread": "thr_01j3k5m7n9p2r4s6t8v0w1x2" - }, - "properties": { - "description": { - "description": "Optional long-form description or notes for the task. Supports plain text.", - "example": "An example description.", - "type": "string" - }, - "due_date": { - "description": "Date and time by which the task should be completed (ISO 8601). Omit to create the task without a due date.", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", - "type": "string" - }, - "links": { - "description": "Arbitrary key-value map of named URLs or references associated with the task (e.g. external ticket links).", - "example": { - "key": "value" - }, - "type": "object" - }, - "metadata": { - "description": "Arbitrary key-value map for storing application-specific data alongside the task. Omit to create the task with no metadata.", - "example": { - "key": "value" - }, - "type": "object" - }, - "name": { - "description": "Human-readable title for the task.", - "example": "Example Name", - "type": "string" - }, - "owner_agent": { - "description": "ID of the agent to assign as owner (`agi_...`). Mutually exclusive with `owner_user`; omit to leave the task unassigned.", - "example": "string", - "type": "string" - }, - "owner_user": { - "description": "ID of the user to assign as owner (`usr_...`). Mutually exclusive with `owner_agent`; omit to leave the task unassigned.", - "example": "string", - "type": "string" - }, - "parent": { - "description": "Create this task as a subtask of an existing top-level task (`tsk_...`). Subtasks nest exactly one level.", - "example": "tsk_01j3k5m7n9p2r4s6t8v0w1x2", - "type": "string" - }, - "priority": { - "description": "Priority level from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when omitted.", - "example": 2, - "type": "integer" - }, - "status": { - "description": "Initial status for the task. One of `\"open\"`, `\"in_progress\"`, or `\"done\"`. Defaults to `\"open\"` when omitted.", - "example": "open", - "type": "string" - }, - "tags": { - "description": "Labels for grouping and filtering (max 20, each up to 40 characters). Stored canonically: lowercase, trimmed, de-duplicated.", - "example": [ - "backend", - "q3-launch" - ], - "items": { - "type": "string" - }, - "type": "array" - }, - "thread": { - "description": "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.", - "example": "thr_01j3k5m7n9p2r4s6t8v0w1x2", - "type": "string" - } - }, - "required": [ - "name" - ], - "type": "object" - }, - "team": { - "description": "Team ID (`tem_...`). The task will be owned by this team.", - "example": "string", - "type": "string" - } - }, - "required": [ - "task" - ], - "type": "object" - } + }, + { + "description": "Optional organization context for privileged callers.", + "example": "string", + "in": "query", + "name": "org", + "required": false, + "schema": { + "type": "string" } }, - "required": true - }, - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Task" - } - } - }, - "description": "The newly created task." + { + "description": "Include blocked and actively leased open tasks with exclusion reasons.", + "example": true, + "in": "query", + "name": "explain", + "required": false, + "schema": { + "type": "boolean" + } }, - "401": { - "description": "Unauthorized" + { + "description": "Only include tasks assigned to the authenticated user.", + "example": true, + "in": "query", + "name": "assigned_to_me", + "required": false, + "schema": { + "type": "boolean" + } }, - "404": { - "description": "Task owner not found" + { + "description": "Only include tasks whose source matches this container. Must be supplied with `source_type` and `source_id`.", + "example": "string", + "in": "query", + "name": "source_scope", + "required": false, + "schema": { + "type": "string" + } }, - "422": { - "description": "Validation error" - } - }, - "summary": "Create a task for an owner", - "x-auth": [ - "publishable_key", - "bearer" - ] - } - }, - "/api/v1/users/{user}/tasks/blocker_cycles": { - "get": { - "description": "Runs an on-demand diagnostic over unfinished tasks owned by the specified\nteam or user and returns a forward cursor-paginated page of complete cyclic\nblocker components. Detection is bounded to owners with at most 100\nunfinished tasks. This endpoint is read-only: cycles do not prevent task\nupdates, lease acquisition, or completion.\n", - "operationId": "get_api_v1_users__user_tasks_blocker_cycles", - "parameters": [ { - "description": "Team ID (`tem_...`) owning the tasks.", + "description": "Only include tasks whose source matches this object kind.", "example": "string", "in": "query", - "name": "team", + "name": "source_type", "required": false, "schema": { "type": "string" } }, { - "description": "User ID (`usr_...`) owning the tasks.", + "description": "Only include tasks whose source matches this object identity.", "example": "string", - "in": "path", - "name": "user", - "required": true, + "in": "query", + "name": "source_id", + "required": false, "schema": { "type": "string" } }, { - "description": "Optional organization context for privileged callers.", + "description": "Only include tasks with this exact epic label.", "example": "string", "in": "query", - "name": "org", + "name": "epic", "required": false, "schema": { "type": "string" } }, { - "description": "Maximum cycle components to return. Defaults to 50; maximum is 100.", + "description": "Maximum number of readiness entries to return. Capped at 100.", "example": 1, "in": "query", "name": "limit", @@ -66193,7 +73287,7 @@ } }, { - "description": "Opaque cursor returned by the preceding page.", + "description": "Opaque cursor returned by the previous page.", "example": "string", "in": "query", "name": "after_cursor", @@ -66208,14 +73302,111 @@ "content": { "application/json": { "schema": { - "description": "On-demand task blocker cycle diagnostics.", + "description": "Cursor-paginated readiness results for the owner.", "example": { "after_cursor": "string", + "authoritative": true, "before_cursor": "string", "data": [ { - "tasks": [ - { + "readiness": "ready", + "reason": "open_blockers", + "task": { + "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "blocked_by_count": 1, + "closed_at": "2024-01-01T00:00:00Z", + "comments_count": 1, + "created_at": "2024-01-01T00:00:00Z", + "created_by_actor": { + "alias": "alice", + "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "name": "Example Name", + "profile_picture": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + } + }, + "created_by_agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "current_lease": { + "expires_at": "2024-01-01T00:00:00Z", + "harness": "string", + "session_name": "Example Name" + }, + "description": "An example description.", + "due_date": "2024-01-01T00:00:00Z", + "epic": "string", + "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "is_blocked": true, + "links": { + "key": "value" + }, + "metadata": { + "key": "value" + }, + "name": "Example Name", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "owner_actor": { + "alias": "alice", + "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "name": "Example Name", + "profile_picture": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + } + }, + "owner_agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "owner_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "priority": 2, + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", + "status": "open", + "subtasks_count": 1, + "tags": [ + "string" + ], + "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "thread": "thr_0aBcDeFgHiJkLmNoPqRsTu", + "updated_at": "2024-01-01T00:00:00Z", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" + } + } + ], + "has_more": true + }, + "properties": { + "after_cursor": { + "example": "string", + "type": "string" + }, + "authoritative": { + "description": "Always false because projections can lag writes and a later claim can race this read.", + "example": true, + "type": "boolean" + }, + "before_cursor": { + "example": "string", + "type": "string" + }, + "data": { + "example": [ + { + "readiness": "ready", + "reason": "open_blockers", + "task": { "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", "blocked_by_count": 1, "closed_at": "2024-01-01T00:00:00Z", @@ -66244,6 +73435,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -66273,6 +73465,9 @@ "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "priority": 2, "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", "status": "open", "subtasks_count": 1, "tags": [ @@ -66283,25 +73478,110 @@ "updated_at": "2024-01-01T00:00:00Z", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" } - ] - } - ], - "has_more": true - }, - "properties": { - "after_cursor": { - "example": "string", - "type": "string" - }, - "before_cursor": { - "example": "string", - "type": "string" - }, - "data": { - "example": [ - { - "tasks": [ - { + } + ], + "items": { + "description": "A task plus the server-calculated reason it is or is not ready.", + "example": { + "readiness": "ready", + "reason": "open_blockers", + "task": { + "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "blocked_by_count": 1, + "closed_at": "2024-01-01T00:00:00Z", + "comments_count": 1, + "created_at": "2024-01-01T00:00:00Z", + "created_by_actor": { + "alias": "alice", + "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "name": "Example Name", + "profile_picture": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + } + }, + "created_by_agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "current_lease": { + "expires_at": "2024-01-01T00:00:00Z", + "harness": "string", + "session_name": "Example Name" + }, + "description": "An example description.", + "due_date": "2024-01-01T00:00:00Z", + "epic": "string", + "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "is_blocked": true, + "links": { + "key": "value" + }, + "metadata": { + "key": "value" + }, + "name": "Example Name", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "owner_actor": { + "alias": "alice", + "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "name": "Example Name", + "profile_picture": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + } + }, + "owner_agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "owner_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "priority": 2, + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", + "status": "open", + "subtasks_count": 1, + "tags": [ + "string" + ], + "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "thread": "thr_0aBcDeFgHiJkLmNoPqRsTu", + "updated_at": "2024-01-01T00:00:00Z", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" + } + }, + "properties": { + "readiness": { + "description": "One of `ready`, `blocked`, or `leased`.", + "enum": [ + "ready", + "blocked", + "leased" + ], + "example": "ready", + "type": "string" + }, + "reason": { + "description": "Stable exclusion reason: `open_blockers` or `active_lease`; omitted when ready.", + "enum": [ + "open_blockers", + "active_lease" + ], + "example": "open_blockers", + "nullable": true, + "type": "string" + }, + "task": { + "description": "The task evaluated for readiness.", + "example": { "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", "blocked_by_count": 1, "closed_at": "2024-01-01T00:00:00Z", @@ -66330,6 +73610,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -66359,6 +73640,9 @@ "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "priority": 2, "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", "status": "open", "subtasks_count": 1, "tags": [ @@ -66368,128 +73652,40 @@ "thread": "thr_0aBcDeFgHiJkLmNoPqRsTu", "updated_at": "2024-01-01T00:00:00Z", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" - } - ] - } - ], - "items": { - "description": "A strongly connected component of unfinished task blocker edges.", - "example": { - "tasks": [ - { - "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", - "blocked_by_count": 1, - "closed_at": "2024-01-01T00:00:00Z", - "comments_count": 1, - "created_at": "2024-01-01T00:00:00Z", - "created_by_actor": { - "alias": "alice", - "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", - "name": "Example Name", - "profile_picture": { - "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", - "height": 600, - "media": "med_0aBcDeFgHiJkLmNoPqRsTu", - "mime_type": "application/json", - "refresh_url": "https://example.com", - "url": "https://example.com", - "width": 800 - } + }, + "properties": { + "agent": { + "description": "ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", + "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" }, - "created_by_agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", - "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", - "current_lease": { - "expires_at": "2024-01-01T00:00:00Z", - "harness": "string", - "session_name": "Example Name" + "blocked_by_count": { + "description": "Number of tasks marked as blocking this task, whether or not they are done (see `GET /tasks/{task}/blockers`). Computed on list/show reads; create/update responses may lag one read behind.", + "example": 1, + "type": "integer" }, - "description": "An example description.", - "due_date": "2024-01-01T00:00:00Z", - "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", - "is_blocked": true, - "links": { - "key": "value" + "closed_at": { + "description": "When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "nullable": true, + "type": "string" }, - "metadata": { - "key": "value" + "comments_count": { + "description": "Total number of comments posted on this task.", + "example": 1, + "type": "integer" }, - "name": "Example Name", - "org": "org_0aBcDeFgHiJkLmNoPqRsTu", - "owner_actor": { - "alias": "alice", - "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", - "name": "Example Name", - "profile_picture": { - "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", - "height": 600, - "media": "med_0aBcDeFgHiJkLmNoPqRsTu", - "mime_type": "application/json", - "refresh_url": "https://example.com", - "url": "https://example.com", - "width": 800 - } + "created_at": { + "description": "When the task was created (ISO 8601).", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "type": "string" }, - "owner_agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", - "owner_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", - "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", - "priority": 2, - "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", - "status": "open", - "subtasks_count": 1, - "tags": [ - "string" - ], - "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", - "thread": "thr_0aBcDeFgHiJkLmNoPqRsTu", - "updated_at": "2024-01-01T00:00:00Z", - "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" - } - ] - }, - "properties": { - "tasks": { - "description": "Every unfinished task in this cyclic blocker component.", - "example": [ - { - "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", - "blocked_by_count": 1, - "closed_at": "2024-01-01T00:00:00Z", - "comments_count": 1, - "created_at": "2024-01-01T00:00:00Z", - "created_by_actor": { - "alias": "alice", - "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", - "name": "Example Name", - "profile_picture": { - "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", - "height": 600, - "media": "med_0aBcDeFgHiJkLmNoPqRsTu", - "mime_type": "application/json", - "refresh_url": "https://example.com", - "url": "https://example.com", - "width": 800 - } - }, - "created_by_agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", - "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", - "current_lease": { - "expires_at": "2024-01-01T00:00:00Z", - "harness": "string", - "session_name": "Example Name" - }, - "description": "An example description.", - "due_date": "2024-01-01T00:00:00Z", - "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", - "is_blocked": true, - "links": { - "key": "value" - }, - "metadata": { - "key": "value" - }, - "name": "Example Name", - "org": "org_0aBcDeFgHiJkLmNoPqRsTu", - "owner_actor": { + "created_by_actor": { + "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).", + "example": { "alias": "alice", "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", "name": "Example Name", @@ -66503,64 +73699,189 @@ "width": 800 } }, - "owner_agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", - "owner_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", - "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", - "priority": 2, - "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", - "status": "open", - "subtasks_count": 1, - "tags": [ - "string" - ], - "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", - "thread": "thr_0aBcDeFgHiJkLmNoPqRsTu", - "updated_at": "2024-01-01T00:00:00Z", - "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" - } - ], - "items": { - "description": "A task representing a unit of work, optionally assignable to a user or agent.", - "example": { - "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", - "blocked_by_count": 1, - "closed_at": "2024-01-01T00:00:00Z", - "comments_count": 1, - "created_at": "2024-01-01T00:00:00Z", - "created_by_actor": { - "alias": "alice", - "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", - "name": "Example Name", + "nullable": true, + "properties": { + "alias": { + "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", + "example": "alice", + "nullable": true, + "type": "string" + }, + "id": { + "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", + "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "nullable": true, + "type": "string" + }, + "name": { + "description": "Display name of the actor shown in the UI. `null` if no name is set.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, "profile_picture": { - "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", - "height": 600, - "media": "med_0aBcDeFgHiJkLmNoPqRsTu", - "mime_type": "application/json", - "refresh_url": "https://example.com", - "url": "https://example.com", - "width": 800 + "description": "Profile picture for the actor. `null` if the actor has no profile picture.", + "example": { + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "height": 600, + "media": "med_0aBcDeFgHiJkLmNoPqRsTu", + "mime_type": "application/json", + "refresh_url": "https://example.com", + "url": "https://example.com", + "width": 800 + }, + "nullable": true, + "properties": { + "file": { + "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", + "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "height": { + "description": "Height of the image in pixels. `null` if not known.", + "example": 600, + "nullable": true, + "type": "integer" + }, + "media": { + "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", + "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "mime_type": { + "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", + "example": "application/json", + "nullable": true, + "type": "string" + }, + "refresh_url": { + "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.", + "example": "https://example.com", + "nullable": true, + "type": "string" + }, + "url": { + "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.", + "example": "https://example.com", + "nullable": true, + "type": "string" + }, + "width": { + "description": "Width of the image in pixels. `null` if not known.", + "example": 800, + "nullable": true, + "type": "integer" + } + }, + "type": "object" } }, - "created_by_agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", - "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", - "current_lease": { + "type": "object" + }, + "created_by_agent": { + "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.", + "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_user": { + "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.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "current_lease": { + "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.", + "example": { "expires_at": "2024-01-01T00:00:00Z", "harness": "string", "session_name": "Example Name" }, - "description": "An example description.", - "due_date": "2024-01-01T00:00:00Z", - "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", - "is_blocked": true, - "links": { + "nullable": true, + "properties": { + "expires_at": { + "description": "Server-calculated lease expiry in ISO 8601 format.", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "type": "string" + }, + "harness": { + "description": "Bounded harness identifier for the coding session.", + "example": "string", + "type": "string" + }, + "session_name": { + "description": "Display name supplied by the coding session that holds the lease.", + "example": "Example Name", + "type": "string" + } + }, + "required": [ + "session_name", + "harness", + "expires_at" + ], + "type": "object" + }, + "description": { + "description": "Long-form description or notes for the task. `null` if no description has been provided.", + "example": "An example description.", + "nullable": true, + "type": "string" + }, + "due_date": { + "description": "Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "nullable": true, + "type": "string" + }, + "epic": { + "description": "Free-form grouping label. `null` when the task is not in an epic.", + "example": "string", + "nullable": true, + "type": "string" + }, + "id": { + "description": "Task ID (`tsk_...`).", + "example": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "is_blocked": { + "description": "`true` while at least one blocking task is not yet done. Informational only — a blocked task can still change status — and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on list/show reads; create/update responses report `false` until the next read.", + "example": true, + "type": "boolean" + }, + "links": { + "description": "Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.", + "example": { "key": "value" }, - "metadata": { + "type": "object" + }, + "metadata": { + "description": "Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.", + "example": { "key": "value" }, - "name": "Example Name", - "org": "org_0aBcDeFgHiJkLmNoPqRsTu", - "owner_actor": { + "type": "object" + }, + "name": { + "description": "Human-readable title of the task.", + "example": "Example Name", + "type": "string" + }, + "org": { + "description": "ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "owner_actor": { + "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).", + "example": { "alias": "alice", "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", "name": "Example Name", @@ -66574,229 +73895,29 @@ "width": 800 } }, - "owner_agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", - "owner_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", - "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", - "priority": 2, - "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", - "status": "open", - "subtasks_count": 1, - "tags": [ - "string" - ], - "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", - "thread": "thr_0aBcDeFgHiJkLmNoPqRsTu", - "updated_at": "2024-01-01T00:00:00Z", - "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" - }, - "properties": { - "agent": { - "description": "ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", - "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "blocked_by_count": { - "description": "Number of tasks marked as blocking this task, whether or not they are done (see `GET /tasks/{task}/blockers`). Computed on list/show reads; create/update responses may lag one read behind.", - "example": 1, - "type": "integer" - }, - "closed_at": { - "description": "When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", - "type": "string" - }, - "comments_count": { - "description": "Total number of comments posted on this task.", - "example": 1, - "type": "integer" - }, - "created_at": { - "description": "When the task was created (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", - "type": "string" - }, - "created_by_actor": { - "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).", - "example": { - "alias": "alice", - "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", - "name": "Example Name", - "profile_picture": { - "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", - "height": 600, - "media": "med_0aBcDeFgHiJkLmNoPqRsTu", - "mime_type": "application/json", - "refresh_url": "https://example.com", - "url": "https://example.com", - "width": 800 - } - }, - "properties": { - "alias": { - "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", - "example": "alice", - "type": "string" - }, - "id": { - "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", - "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", - "type": "string" - }, - "name": { - "description": "Display name of the actor shown in the UI. `null` if no name is set.", - "example": "Example Name", - "type": "string" - }, - "profile_picture": { - "description": "Profile picture for the actor. `null` if the actor has no profile picture.", - "example": { - "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", - "height": 600, - "media": "med_0aBcDeFgHiJkLmNoPqRsTu", - "mime_type": "application/json", - "refresh_url": "https://example.com", - "url": "https://example.com", - "width": 800 - }, - "properties": { - "file": { - "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", - "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "height": { - "description": "Height of the image in pixels. `null` if not known.", - "example": 600, - "type": "integer" - }, - "media": { - "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", - "example": "med_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "mime_type": { - "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", - "example": "application/json", - "type": "string" - }, - "refresh_url": { - "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.", - "example": "https://example.com", - "type": "string" - }, - "url": { - "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.", - "example": "https://example.com", - "type": "string" - }, - "width": { - "description": "Width of the image in pixels. `null` if not known.", - "example": 800, - "type": "integer" - } - }, - "type": "object" - } - }, - "type": "object" - }, - "created_by_agent": { - "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.", - "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "created_by_user": { - "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.", - "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "current_lease": { - "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.", - "example": { - "expires_at": "2024-01-01T00:00:00Z", - "harness": "string", - "session_name": "Example Name" - }, - "nullable": true, - "properties": { - "expires_at": { - "description": "Server-calculated lease expiry in ISO 8601 format.", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", - "type": "string" - }, - "harness": { - "description": "Bounded harness identifier for the coding session.", - "example": "string", - "type": "string" - }, - "session_name": { - "description": "Display name supplied by the coding session that holds the lease.", - "example": "Example Name", - "type": "string" - } + "nullable": true, + "properties": { + "alias": { + "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", + "example": "alice", + "nullable": true, + "type": "string" }, - "required": [ - "session_name", - "harness", - "expires_at" - ], - "type": "object" - }, - "description": { - "description": "Long-form description or notes for the task. `null` if no description has been provided.", - "example": "An example description.", - "type": "string" - }, - "due_date": { - "description": "Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", - "type": "string" - }, - "id": { - "description": "Task ID (`tsk_...`).", - "example": "tsk_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "is_blocked": { - "description": "`true` while at least one blocking task is not yet done. Informational only — a blocked task can still change status — and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on list/show reads; create/update responses report `false` until the next read.", - "example": true, - "type": "boolean" - }, - "links": { - "description": "Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.", - "example": { - "key": "value" + "id": { + "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", + "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "nullable": true, + "type": "string" }, - "type": "object" - }, - "metadata": { - "description": "Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.", - "example": { - "key": "value" + "name": { + "description": "Display name of the actor shown in the UI. `null` if no name is set.", + "example": "Example Name", + "nullable": true, + "type": "string" }, - "type": "object" - }, - "name": { - "description": "Human-readable title of the task.", - "example": "Example Name", - "type": "string" - }, - "org": { - "description": "ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", - "example": "org_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "owner_actor": { - "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).", - "example": { - "alias": "alice", - "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", - "name": "Example Name", - "profile_picture": { + "profile_picture": { + "description": "Profile picture for the actor. `null` if the actor has no profile picture.", + "example": { "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", "height": 600, "media": "med_0aBcDeFgHiJkLmNoPqRsTu", @@ -66804,156 +73925,160 @@ "refresh_url": "https://example.com", "url": "https://example.com", "width": 800 - } - }, - "properties": { - "alias": { - "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", - "example": "alice", - "type": "string" - }, - "id": { - "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", - "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", - "type": "string" }, - "name": { - "description": "Display name of the actor shown in the UI. `null` if no name is set.", - "example": "Example Name", - "type": "string" - }, - "profile_picture": { - "description": "Profile picture for the actor. `null` if the actor has no profile picture.", - "example": { - "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", - "height": 600, - "media": "med_0aBcDeFgHiJkLmNoPqRsTu", - "mime_type": "application/json", - "refresh_url": "https://example.com", - "url": "https://example.com", - "width": 800 + "nullable": true, + "properties": { + "file": { + "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", + "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" }, - "properties": { - "file": { - "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", - "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "height": { - "description": "Height of the image in pixels. `null` if not known.", - "example": 600, - "type": "integer" - }, - "media": { - "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", - "example": "med_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "mime_type": { - "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", - "example": "application/json", - "type": "string" - }, - "refresh_url": { - "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.", - "example": "https://example.com", - "type": "string" - }, - "url": { - "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.", - "example": "https://example.com", - "type": "string" - }, - "width": { - "description": "Width of the image in pixels. `null` if not known.", - "example": 800, - "type": "integer" - } + "height": { + "description": "Height of the image in pixels. `null` if not known.", + "example": 600, + "nullable": true, + "type": "integer" }, - "type": "object" - } - }, - "type": "object" - }, - "owner_agent": { - "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.", - "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "owner_user": { - "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.", - "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "parent": { - "description": "ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks. Subtasks nest exactly one level.", - "example": "tsk_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "priority": { - "description": "Priority level of the task from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when not explicitly set.", - "example": 2, - "type": "integer" - }, - "sandbox": { - "description": "ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", - "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "status": { - "description": "Current status of the task. One of `\"open\"`, `\"in_progress\"`, or `\"done\"`.", - "example": "open", - "type": "string" - }, - "subtasks_count": { - "description": "Number of subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.", - "example": 1, - "type": "integer" - }, - "tags": { - "description": "Labels for grouping and filtering, stored lowercase and de-duplicated. Empty array when untagged.", - "example": [ - "string" - ], - "items": { - "type": "string" - }, - "type": "array" - }, - "team": { - "description": "ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", - "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "thread": { - "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.", - "example": "thr_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" + "media": { + "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", + "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "mime_type": { + "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", + "example": "application/json", + "nullable": true, + "type": "string" + }, + "refresh_url": { + "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.", + "example": "https://example.com", + "nullable": true, + "type": "string" + }, + "url": { + "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.", + "example": "https://example.com", + "nullable": true, + "type": "string" + }, + "width": { + "description": "Width of the image in pixels. `null` if not known.", + "example": 800, + "nullable": true, + "type": "integer" + } + }, + "type": "object" + } }, - "updated_at": { - "description": "When the task was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "type": "object" + }, + "owner_agent": { + "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.", + "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "owner_user": { + "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.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "parent": { + "description": "ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks. Subtasks nest exactly one level.", + "example": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "priority": { + "description": "Priority level of the task from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when not explicitly set.", + "example": 2, + "type": "integer" + }, + "sandbox": { + "description": "ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", + "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "source_id": { + "description": "Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", + "example": "string", + "nullable": true, + "type": "string" + }, + "source_scope": { + "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`.", + "example": "string", + "nullable": true, + "type": "string" + }, + "source_type": { + "description": "Kind of source object (for example `repository`). `null` when the task has no source.", + "example": "string", + "nullable": true, + "type": "string" + }, + "status": { + "description": "Current status of the task. One of `\"open\"`, `\"in_progress\"`, or `\"done\"`.", + "example": "open", + "type": "string" + }, + "subtasks_count": { + "description": "Number of subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.", + "example": 1, + "type": "integer" + }, + "tags": { + "description": "Labels for grouping and filtering, stored lowercase and de-duplicated. Empty array when untagged.", + "example": [ + "string" + ], + "items": { "type": "string" }, - "user": { - "description": "ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", - "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - } + "type": "array" }, - "required": [ - "id", - "name", - "status" - ], - "type": "object" + "team": { + "description": "ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "thread": { + "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.", + "example": "thr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "updated_at": { + "description": "When the task was last modified (ISO 8601).", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "type": "string" + }, + "user": { + "description": "ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + } }, - "type": "array" + "required": [ + "id", + "name", + "status" + ], + "type": "object" } }, "required": [ - "tasks" + "task", + "readiness" ], "type": "object" }, @@ -66966,6 +74091,7 @@ }, "required": [ "data", + "authoritative", "has_more" ], "type": "object" @@ -66981,10 +74107,10 @@ "description": "Task owner not found" }, "422": { - "description": "Invalid owner context or diagnostic limit" + "description": "Invalid owner context or pagination cursor" } }, - "summary": "List task blocker cycles", + "summary": "List an owner's ready tasks", "x-auth": [ "publishable_key", "bearer" @@ -67106,6 +74232,46 @@ "type": "string" } }, + { + "description": "Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_id`.", + "example": "string", + "in": "query", + "name": "source_scope", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Return only tasks whose source matches this object kind.", + "example": "string", + "in": "query", + "name": "source_type", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Return only tasks whose source matches this object identity.", + "example": "string", + "in": "query", + "name": "source_id", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Return only tasks with this exact epic label.", + "example": "string", + "in": "query", + "name": "epic", + "required": false, + "schema": { + "type": "string" + } + }, { "description": "Maximum number of tasks to return. Capped at 100.", "example": 1, @@ -67166,6 +74332,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -67195,6 +74362,9 @@ "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "priority": 2, "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", "status": "open", "subtasks_count": 1, "tags": [ @@ -67250,6 +74420,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -67279,6 +74450,9 @@ "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "priority": 2, "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", "status": "open", "subtasks_count": 1, "tags": [ @@ -67321,6 +74495,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -67350,6 +74525,9 @@ "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "priority": 2, "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", "status": "open", "subtasks_count": 1, "tags": [ @@ -67364,6 +74542,7 @@ "agent": { "description": "ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "blocked_by_count": { @@ -67375,6 +74554,7 @@ "description": "When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", "example": "2024-01-01T00:00:00Z", "format": "date-time", + "nullable": true, "type": "string" }, "comments_count": { @@ -67404,20 +74584,24 @@ "width": 800 } }, + "nullable": true, "properties": { "alias": { "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", "example": "alice", + "nullable": true, "type": "string" }, "id": { "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "nullable": true, "type": "string" }, "name": { "description": "Display name of the actor shown in the UI. `null` if no name is set.", "example": "Example Name", + "nullable": true, "type": "string" }, "profile_picture": { @@ -67431,40 +74615,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -67476,11 +74668,13 @@ "created_by_agent": { "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.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "created_by_user": { "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.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "current_lease": { @@ -67519,12 +74713,20 @@ "description": { "description": "Long-form description or notes for the task. `null` if no description has been provided.", "example": "An example description.", + "nullable": true, "type": "string" }, "due_date": { "description": "Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", "example": "2024-01-01T00:00:00Z", "format": "date-time", + "nullable": true, + "type": "string" + }, + "epic": { + "description": "Free-form grouping label. `null` when the task is not in an epic.", + "example": "string", + "nullable": true, "type": "string" }, "id": { @@ -67559,6 +74761,7 @@ "org": { "description": "ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "owner_actor": { @@ -67577,20 +74780,24 @@ "width": 800 } }, + "nullable": true, "properties": { "alias": { "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", "example": "alice", + "nullable": true, "type": "string" }, "id": { "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "nullable": true, "type": "string" }, "name": { "description": "Display name of the actor shown in the UI. `null` if no name is set.", "example": "Example Name", + "nullable": true, "type": "string" }, "profile_picture": { @@ -67604,40 +74811,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -67649,16 +74864,19 @@ "owner_agent": { "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.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "owner_user": { "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.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "parent": { "description": "ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks. Subtasks nest exactly one level.", "example": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "priority": { @@ -67669,6 +74887,25 @@ "sandbox": { "description": "ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "source_id": { + "description": "Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", + "example": "string", + "nullable": true, + "type": "string" + }, + "source_scope": { + "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`.", + "example": "string", + "nullable": true, + "type": "string" + }, + "source_type": { + "description": "Kind of source object (for example `repository`). `null` when the task has no source.", + "example": "string", + "nullable": true, "type": "string" }, "status": { @@ -67694,11 +74931,13 @@ "team": { "description": "ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "thread": { "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.", "example": "thr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "updated_at": { @@ -67710,6 +74949,7 @@ "user": { "description": "ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" } }, @@ -67998,7 +75238,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "participant": [ @@ -68009,6 +75249,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -68019,6 +75264,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -68224,7 +75470,7 @@ ], "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "title": "Example Title", - "ttl": 3600, + "ttl": "2026-08-15T12:00:00", "unread_count": 5, "updated_at": "2024-01-01T00:00:00Z", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", @@ -68389,7 +75635,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "participant": [ @@ -68400,6 +75646,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -68410,6 +75661,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -68615,7 +75867,7 @@ ], "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "title": "Example Title", - "ttl": 3600, + "ttl": "2026-08-15T12:00:00", "unread_count": 5, "updated_at": "2024-01-01T00:00:00Z", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", @@ -68626,7 +75878,7 @@ "description": "A chat thread, representing a conversation channel that can be owned by a user, team, or agent and may contain messages, participants, and AI agent activity.", "example": { "agent_user": "agi_0aBcDeFgHiJkLmNoPqRsTu", - "created_at": "2024-01-01T00:00:00Z", + "created_at": "string", "creator": "usr_0aBcDeFgHiJkLmNoPqRsTu", "description": "An example description.", "id": "string", @@ -68636,7 +75888,7 @@ "is_unlisted": true, "key": "string", "kind": "string", - "last_activity": "2024-01-01T00:00:00Z", + "last_activity": "string", "last_message_preview": "Sounds good — I'll ship the fix tomorrow.", "last_message_sender": "Alice Chen", "metadata": { @@ -68777,7 +76029,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "participant": [ @@ -68788,6 +76040,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -68798,6 +76055,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -69003,9 +76261,9 @@ ], "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "title": "Example Title", - "ttl": 3600, + "ttl": "2026-08-15T12:00:00", "unread_count": 5, - "updated_at": "2024-01-01T00:00:00Z", + "updated_at": "string", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "team" }, @@ -69013,17 +76271,18 @@ "agent_user": { "description": "ID of the agent that owns this thread (`agt_...`). `null` for user-owned or team-owned threads.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "created_at": { "description": "When the thread was created (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "creator": { "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.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "oneOf": [ { "type": "string" @@ -69034,6 +76293,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -69044,6 +76308,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" }, @@ -69051,21 +76316,55 @@ "alias": { "description": "Short handle or alias for the user. `null` if not set.", "example": "jdoe", + "nullable": true, "type": "string" }, "app": { "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.", "example": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "app_name": { "description": "Display name of the user's app. `null` when the app association was not preloaded by the caller.", "example": "Example Name", + "nullable": true, + "type": "string" + }, + "created_by_agent_user": { + "description": "Agent user that created this account (`usr_...`). `null` unless an agent created it.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_developer": { + "description": "Developer account that created this user (`dva_...`). `null` unless created via a developer token.", + "example": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_org": { + "description": "Org of the principal that created this user (`org_...`). `null` on legacy rows.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_team": { + "description": "Team that created this user (`tem_...`). `null` unless created as a team.", + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_user": { + "description": "User who created this account (`usr_...`). `null` on self-signup or legacy rows.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "email": { "description": "Email address of the user.", "example": "user@example.com", + "nullable": true, "type": "string" }, "id": { @@ -69088,31 +76387,43 @@ "name": { "description": "Full display name of the user. `null` if the user has not set a name.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "description": "ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_name": { "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.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_role": { "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.", "example": "member", + "nullable": true, + "type": "string" + }, + "org_slug": { + "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.", + "example": "example-slug", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "sandbox_name": { "description": "Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.", "example": "Example Name", + "nullable": true, "type": "string" } }, @@ -69126,6 +76437,7 @@ "description": { "description": "Optional description or purpose statement for the thread. `null` if not set.", "example": "An example description.", + "nullable": true, "type": "string" }, "id": { @@ -69156,27 +76468,31 @@ "key": { "description": "Application-defined stable key that uniquely identifies the thread within its scope. Useful for idempotent creation. `null` if not set.", "example": "string", + "nullable": true, "type": "string" }, "kind": { - "description": "Thread subtype: `\"standard\"` for ordinary threads, `\"slack_mirror\"` for the membership-strict mirror of a Slack channel, `\"slashwork_mirror\"` for the membership-strict mirror of a Slashwork group. Read-only — derived server-side at creation, never accepted from params.", + "description": "Thread subtype: `\"standard\"` for ordinary threads, `\"personal\"` for a user-and-owned-agents roster, `\"slack_mirror\"` for the membership-strict mirror of a Slack channel, or `\"slashwork_mirror\"` for the membership-strict mirror of a Slashwork group. `personal` is an explicit user-thread creation option; mirror kinds are server-derived.", "example": "string", + "nullable": true, "type": "string" }, "last_activity": { "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.", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", + "nullable": true, "type": "string" }, "last_message_preview": { "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.", "example": "Sounds good — I'll ship the fix tomorrow.", + "nullable": true, "type": "string" }, "last_message_sender": { "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.", "example": "Alice Chen", + "nullable": true, "type": "string" }, "metadata": { @@ -69184,6 +76500,7 @@ "example": { "key": "value" }, + "nullable": true, "type": "object" }, "muted": { @@ -69194,6 +76511,7 @@ "org": { "description": "ID of the organization this thread belongs to (`org_...`). `null` for threads outside an org context.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "parent_message": { @@ -69331,9 +76649,10 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, + "nullable": true, "properties": { "acl": { "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.", @@ -69365,6 +76684,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -69546,16 +76866,19 @@ "alias": { "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", "example": "alice", + "nullable": true, "type": "string" }, "id": { "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "nullable": true, "type": "string" }, "name": { "description": "Display name of the actor shown in the UI. `null` if no name is set.", "example": "Example Name", + "nullable": true, "type": "string" }, "profile_picture": { @@ -69569,40 +76892,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -69616,6 +76947,7 @@ "agent": { "description": "ID of the agent user that sent this message (`agi_...`). `null` for messages sent by human users.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "agent_mode": { @@ -69625,6 +76957,7 @@ "embedded" ], "example": "cli", + "nullable": true, "type": "string" }, "attachments": { @@ -69737,21 +77070,25 @@ "content_type": { "description": "MIME type of the attached file, e.g. `\"image/png\"` or `\"application/pdf\"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.", "example": "application/json", + "nullable": true, "type": "string" }, "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "filename": { "description": "Original filename of the attached file, e.g. `\"report.pdf\"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.", "example": "string", + "nullable": true, "type": "string" }, "height": { "description": "Height in pixels of the media item. Present on `media` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "id": { @@ -69762,6 +77099,7 @@ "image_height": { "description": "Height in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "image_source": { @@ -69775,40 +77113,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -69817,31 +77163,35 @@ "image_url": { "description": "URL of the preview image extracted from the scraped page. Present on `scraped_link` type only. `null` otherwise.", "example": "https://example.com", + "nullable": true, "type": "string" }, "image_width": { "description": "Width in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "media_type": { - "description": "The media category, e.g. `\"video\"` or `\"audio\"`. Present on `media` type only. `null` otherwise.", + "description": "The media category, e.g. `\"video\"` or `\"audio\"`. Present on `media` type only; omitted otherwise.", "example": "application/json", "type": "string" }, "name": { "description": "Display name of the media item. Present on `media` type only. `null` otherwise.", "example": "Example Name", + "nullable": true, "type": "string" }, "object": { - "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`. `null` on other types.", + "description": "The full embedded object payload. For `task` type, contains the task record. For `action` type, contains the action definition. For `chart` type, contains the chart with its inline `spec`. Omitted on other types.", "example": {}, "type": "object" }, "title": { "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.", "example": "Example Title", + "nullable": true, "type": "string" }, "type": { @@ -69852,10 +77202,11 @@ "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "variants": { - "description": "Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only. `null` otherwise.", + "description": "Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only; omitted otherwise.", "example": [ { "content_type": "application/json", @@ -69906,6 +77257,7 @@ "content_type": { "description": "MIME type of this variant's file (e.g., `\"image/jpeg\"`, `\"video/mp4\"`). `null` if the file is not loaded.", "example": "application/json", + "nullable": true, "type": "string" }, "created_at": { @@ -69922,11 +77274,13 @@ "filename": { "description": "Original filename of the uploaded file for this variant. `null` if the file is not loaded.", "example": "string", + "nullable": true, "type": "string" }, "height": { "description": "Height of this variant in pixels. `null` if not recorded.", "example": 600, + "nullable": true, "type": "integer" }, "id": { @@ -69945,40 +77299,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -69993,6 +77355,7 @@ "url": { "description": "Signed download URL for this variant, resolved at request time. `null` if the file is unavailable.", "example": "https://example.com", + "nullable": true, "type": "string" }, "variant_key": { @@ -70003,6 +77366,7 @@ "width": { "description": "Width of this variant in pixels. `null` if not recorded.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -70016,11 +77380,13 @@ "version": { "description": "Version number of the attached artifact at the time of attachment. Present on `artifact` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "width": { "description": "Width in pixels of the media item. Present on `media` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" } }, @@ -70035,17 +77401,18 @@ "branched_thread": { "description": "ID of the thread that was branched from this message (`thr_...`). `null` if this message has not spawned a branch thread.", "example": "string", + "nullable": true, "type": "string" }, "content": { "description": "Text content of the message. `null` for messages that contain only attachments.", "example": "Hello, how can I help you today?", + "nullable": true, "type": "string" }, "created_at": { "description": "When the message was posted (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "has_replies": { @@ -70061,6 +77428,7 @@ "idempotency_key": { "description": "Client-supplied idempotency key used to deduplicate message sends. `null` if the sender did not provide one.", "example": "01234567-89ab-cdef-0123-456789abcdef", + "nullable": true, "type": "string" }, "is_deleted": { @@ -70071,6 +77439,7 @@ "legacy_agent": { "description": "Identifier of the legacy chat agent that sent this message, if applicable. `null` for messages sent by users or modern agent users.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -70083,6 +77452,7 @@ "org": { "description": "ID of the organization that owns this message (`org_...`).", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "reactions": { @@ -70134,6 +77504,7 @@ "rendering_mode": { "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.", "example": "reply", + "nullable": true, "type": "string" }, "replies": { @@ -70149,11 +77520,13 @@ "replies_after_cursor": { "description": "Opaque pagination cursor to fetch replies posted after the current page. Only present when inline replies are included in the response.", "example": "string", + "nullable": true, "type": "string" }, "replies_before_cursor": { "description": "Opaque pagination cursor to fetch replies posted before the current page. Only present when inline replies are included in the response.", "example": "string", + "nullable": true, "type": "string" }, "reply_count": { @@ -70296,9 +77669,10 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, + "nullable": true, "type": "object" }, "root_message_id": { @@ -70310,27 +77684,180 @@ "sandbox": { "description": "ID of the developer sandbox this message belongs to (`dsb_...`). `null` for non-sandbox messages.", "example": "string", + "nullable": true, "type": "string" }, "team": { "description": "ID of the team this message is scoped to (`tem_...`). `null` if the message is not team-scoped.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "thread": { - "description": "ID of the thread this message belongs to (`thr_...`). `null` for messages not yet associated with a thread.", + "description": "ID of the thread this message belongs to (`thr_...`).", "example": "string", "type": "string" }, "type": { "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.", "example": "note", + "nullable": true, "type": "string" }, "user": { "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.", - "example": "string", - "type": "string" + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "oneOf": [ + { + "type": "string" + }, + { + "description": "A platform user account. Represents a human or system actor that can own threads, belong to an organization, and interact with the API.", + "example": { + "alias": "jdoe", + "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "email": "user@example.com", + "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "is_system_user": true, + "metadata": { + "key": "value" + }, + "name": "Example Name", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "org_name": "Example Name", + "org_role": "member", + "org_slug": "example-slug", + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "sandbox_name": "Example Name" + }, + "properties": { + "alias": { + "description": "Short handle or alias for the user. `null` if not set.", + "example": "jdoe", + "nullable": true, + "type": "string" + }, + "app": { + "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.", + "example": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "app_name": { + "description": "Display name of the user's app. `null` when the app association was not preloaded by the caller.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "created_by_agent_user": { + "description": "Agent user that created this account (`usr_...`). `null` unless an agent created it.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_developer": { + "description": "Developer account that created this user (`dva_...`). `null` unless created via a developer token.", + "example": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_org": { + "description": "Org of the principal that created this user (`org_...`). `null` on legacy rows.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_team": { + "description": "Team that created this user (`tem_...`). `null` unless created as a team.", + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_user": { + "description": "User who created this account (`usr_...`). `null` on self-signup or legacy rows.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "email": { + "description": "Email address of the user.", + "example": "user@example.com", + "nullable": true, + "type": "string" + }, + "id": { + "description": "User ID (`usr_...`).", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "is_system_user": { + "description": "`true` if this account is an internal system user rather than a human. System users are created automatically by the platform.", + "example": true, + "type": "boolean" + }, + "metadata": { + "description": "Arbitrary key-value metadata attached to the user. Defaults to an empty object.", + "example": { + "key": "value" + }, + "type": "object" + }, + "name": { + "description": "Full display name of the user. `null` if the user has not set a name.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "org": { + "description": "ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "org_name": { + "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.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "org_role": { + "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.", + "example": "member", + "nullable": true, + "type": "string" + }, + "org_slug": { + "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.", + "example": "example-slug", + "nullable": true, + "type": "string" + }, + "sandbox": { + "description": "ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.", + "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "sandbox_name": { + "description": "Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.", + "example": "Example Name", + "nullable": true, + "type": "string" + } + }, + "required": [ + "id" + ], + "type": "object" + } + ] }, "visibility": { "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.", @@ -70364,6 +77891,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -70374,6 +77906,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -70384,6 +77917,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -70394,6 +77932,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" }, @@ -70401,21 +77940,55 @@ "alias": { "description": "Short handle or alias for the user. `null` if not set.", "example": "jdoe", + "nullable": true, "type": "string" }, "app": { "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.", "example": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "app_name": { "description": "Display name of the user's app. `null` when the app association was not preloaded by the caller.", "example": "Example Name", + "nullable": true, + "type": "string" + }, + "created_by_agent_user": { + "description": "Agent user that created this account (`usr_...`). `null` unless an agent created it.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_developer": { + "description": "Developer account that created this user (`dva_...`). `null` unless created via a developer token.", + "example": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_org": { + "description": "Org of the principal that created this user (`org_...`). `null` on legacy rows.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_team": { + "description": "Team that created this user (`tem_...`). `null` unless created as a team.", + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_user": { + "description": "User who created this account (`usr_...`). `null` on self-signup or legacy rows.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "email": { "description": "Email address of the user.", "example": "user@example.com", + "nullable": true, "type": "string" }, "id": { @@ -70438,31 +78011,43 @@ "name": { "description": "Full display name of the user. `null` if the user has not set a name.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "description": "ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_name": { "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.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_role": { "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.", "example": "member", + "nullable": true, + "type": "string" + }, + "org_slug": { + "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.", + "example": "example-slug", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "sandbox_name": { "description": "Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.", "example": "Example Name", + "nullable": true, "type": "string" } }, @@ -70700,7 +78285,7 @@ ] }, "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", - "created_at": "2024-01-01T00:00:00Z", + "created_at": "string", "default_model": "claude-3-7-sonnet-latest", "description": "An example description.", "email": "user@example.com", @@ -70848,9 +78433,10 @@ }, "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "template_upgrade_available": true, - "updated_at": "2024-01-01T00:00:00Z", + "updated_at": "string", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" }, + "nullable": true, "properties": { "acl": { "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.", @@ -70882,6 +78468,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -71032,23 +78619,25 @@ }, "created_at": { "description": "When the agent was created (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "default_model": { "description": "Default LLM model identifier used by this agent when no model is specified at runtime (e.g. `\"claude-3-7-sonnet-latest\"`).", "example": "claude-3-7-sonnet-latest", + "nullable": true, "type": "string" }, "description": { "description": "Human-readable description of what the agent does. `null` if not set.", "example": "An example description.", + "nullable": true, "type": "string" }, "email": { "description": "Email address provisioned for this agent. `null` if email delivery is not configured.", "example": "user@example.com", + "nullable": true, "type": "string" }, "id": { @@ -71059,16 +78648,19 @@ "identity": { "description": "System-level identity prompt that shapes the agent's persona and behavior.", "example": "You are a helpful assistant that answers questions about ArchAstro products.", + "nullable": true, "type": "string" }, "last_applied_template_config": { "description": "ID of the AgentTemplate config (`cfg_...`) this agent was last provisioned or updated from. `null` for manually created agents.", "example": "cfg_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "lookup_key": { "description": "Stable, user-defined identifier for this agent within the application. Unique per app.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -71086,26 +78678,31 @@ "org": { "description": "ID of the organization this agent belongs to (`org_...`). `null` if the agent is not org-scoped.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_name": { "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.", "example": "Example Name", + "nullable": true, "type": "string" }, "originator": { "description": "Free-form label identifying the source or author that created this agent (e.g. a username or pipeline name).", "example": "deploy-pipeline", + "nullable": true, "type": "string" }, "phone_number": { "description": "Phone number provisioned for this agent. `null` if SMS is not configured.", "example": "+15555550123", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the sandbox environment this agent is scoped to (`dsb_...`). `null` in production deployments.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "source_solution": { @@ -71239,6 +78836,7 @@ "virtual_path": "string" } }, + "nullable": true, "properties": { "current_solution": { "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.", @@ -71313,13 +78911,13 @@ }, "created_at": { "description": "When the Solution config was first imported (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "events": { @@ -71335,6 +78933,7 @@ "image_url": { "description": "Absolute URL of the Solution's cover image — the bundled asset the body's `image:` field names. A stable, non-expiring capability URL (like `org_logo.url`), safe to hold in caches and OpenGraph tags; it 404s if the Solution stops declaring a cover. `null` when the Solution has no cover image, and always `null` for org-scoped rows — the permanent URL is minted for system-scope (catalog) Solutions only.", "example": "https://example.com", + "nullable": true, "type": "string" }, "kind": { @@ -71345,16 +78944,19 @@ "latest_solution": { "description": "When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "latest_version": { "description": "When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", "example": "1.0.0", + "nullable": true, "type": "string" }, "lookup_key": { "description": "The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -71367,11 +78969,13 @@ "name": { "description": "Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "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.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_logo": { @@ -71385,40 +78989,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -71427,11 +79039,13 @@ "org_name": { "description": "Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_slug": { "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.", "example": "example-slug", + "nullable": true, "type": "string" }, "owners": { @@ -71447,6 +79061,7 @@ "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "screenshot_urls": { @@ -71462,11 +79077,13 @@ "solution_id": { "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.", "example": "01234567-89ab-cdef-0123-456789abcdef", + "nullable": true, "type": "string" }, "solution_version": { "description": "Semver string declared in the Solution body (e.g. `\"1.2.0\"`). `null` when the body does not declare a version.", "example": "1.2.0", + "nullable": true, "type": "string" }, "tag_keys": { @@ -71482,6 +79099,7 @@ "template_kind": { "description": "Wrapped template kind — `\"AgentTemplate\"`, `\"AutomationTemplate\"`, `\"AgentRoutineTemplate\"`, `\"AgentToolTemplate\"`, `\"AgentComputerTemplate\"`, or `\"SolutionTemplateRef\"` for ref-mode bundles.", "example": "AgentTemplate", + "nullable": true, "type": "string" }, "templates": { @@ -71514,6 +79132,7 @@ "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "details": { @@ -71521,6 +79140,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -71545,12 +79165,13 @@ }, "properties": { "automation_type": { - "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`).", + "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", "example": "string", + "nullable": true, "type": "string" }, "invoke_contract": { - "description": "Schema-driven payload and participant inputs for an invoked automation. Used by installation clients to collect locked prefills before provisioning.", + "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.", "example": { "input_schema": {}, "participants": [ @@ -71566,10 +79187,12 @@ "payload": {} } }, + "nullable": true, "properties": { "input_schema": { "description": "JSON Schema validated against the whole invoke payload, from the automation's `input_schema_config`. `null` when none is configured.", "example": {}, + "nullable": true, "type": "object" }, "participants": { @@ -71590,10 +79213,12 @@ "required": true, "type": "agent_user" }, + "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", "example": "An example description.", + "nullable": true, "type": "string" }, "name": { @@ -71619,6 +79244,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -71667,11 +79293,13 @@ "display_name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "id": { "description": "Template config ID (`cfg_...`). `null` for inline-only templates.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "kind": { @@ -71682,21 +79310,25 @@ "lookup_key": { "description": "Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", "example": "string", + "nullable": true, "type": "string" }, "name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "virtual_path": { "description": "Stable virtual path assigned to the template config. `null` when no virtual path was set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -71709,8 +79341,7 @@ }, "updated_at": { "description": "When the Solution config was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "upgrade_available": { @@ -71721,6 +79352,7 @@ "virtual_path": { "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.", "example": "string", + "nullable": true, "type": "string" } }, @@ -71806,13 +79438,13 @@ }, "created_at": { "description": "When the Solution config was first imported (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "events": { @@ -71828,6 +79460,7 @@ "image_url": { "description": "Absolute URL of the Solution's cover image — the bundled asset the body's `image:` field names. A stable, non-expiring capability URL (like `org_logo.url`), safe to hold in caches and OpenGraph tags; it 404s if the Solution stops declaring a cover. `null` when the Solution has no cover image, and always `null` for org-scoped rows — the permanent URL is minted for system-scope (catalog) Solutions only.", "example": "https://example.com", + "nullable": true, "type": "string" }, "kind": { @@ -71838,16 +79471,19 @@ "latest_solution": { "description": "When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "latest_version": { "description": "When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", "example": "1.0.0", + "nullable": true, "type": "string" }, "lookup_key": { "description": "The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -71860,11 +79496,13 @@ "name": { "description": "Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "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.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_logo": { @@ -71878,40 +79516,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -71920,11 +79566,13 @@ "org_name": { "description": "Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_slug": { "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.", "example": "example-slug", + "nullable": true, "type": "string" }, "owners": { @@ -71940,6 +79588,7 @@ "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "screenshot_urls": { @@ -71955,11 +79604,13 @@ "solution_id": { "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.", "example": "01234567-89ab-cdef-0123-456789abcdef", + "nullable": true, "type": "string" }, "solution_version": { "description": "Semver string declared in the Solution body (e.g. `\"1.2.0\"`). `null` when the body does not declare a version.", "example": "1.2.0", + "nullable": true, "type": "string" }, "tag_keys": { @@ -71975,6 +79626,7 @@ "template_kind": { "description": "Wrapped template kind — `\"AgentTemplate\"`, `\"AutomationTemplate\"`, `\"AgentRoutineTemplate\"`, `\"AgentToolTemplate\"`, `\"AgentComputerTemplate\"`, or `\"SolutionTemplateRef\"` for ref-mode bundles.", "example": "AgentTemplate", + "nullable": true, "type": "string" }, "templates": { @@ -72007,6 +79659,7 @@ "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "details": { @@ -72014,6 +79667,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -72038,12 +79692,13 @@ }, "properties": { "automation_type": { - "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`).", + "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", "example": "string", + "nullable": true, "type": "string" }, "invoke_contract": { - "description": "Schema-driven payload and participant inputs for an invoked automation. Used by installation clients to collect locked prefills before provisioning.", + "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.", "example": { "input_schema": {}, "participants": [ @@ -72059,10 +79714,12 @@ "payload": {} } }, + "nullable": true, "properties": { "input_schema": { "description": "JSON Schema validated against the whole invoke payload, from the automation's `input_schema_config`. `null` when none is configured.", "example": {}, + "nullable": true, "type": "object" }, "participants": { @@ -72083,10 +79740,12 @@ "required": true, "type": "agent_user" }, + "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", "example": "An example description.", + "nullable": true, "type": "string" }, "name": { @@ -72112,6 +79771,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -72160,11 +79820,13 @@ "display_name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "id": { "description": "Template config ID (`cfg_...`). `null` for inline-only templates.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "kind": { @@ -72175,21 +79837,25 @@ "lookup_key": { "description": "Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", "example": "string", + "nullable": true, "type": "string" }, "name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "virtual_path": { "description": "Stable virtual path assigned to the template config. `null` when no virtual path was set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -72202,8 +79868,7 @@ }, "updated_at": { "description": "When the Solution config was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "upgrade_available": { @@ -72214,6 +79879,7 @@ "virtual_path": { "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.", "example": "string", + "nullable": true, "type": "string" } }, @@ -72249,11 +79915,13 @@ "description": { "description": "Description of the template from the config body. `null` if the current version has no `description` field.", "example": "An example description.", + "nullable": true, "type": "string" }, "display_name": { "description": "Human-readable display name from the config body. `null` if the current version has no `display_name` field.", "example": "Example Name", + "nullable": true, "type": "string" }, "id": { @@ -72269,11 +79937,13 @@ "lookup_key": { "description": "Stable lookup key assigned to this template config. `null` if no lookup key is set.", "example": "string", + "nullable": true, "type": "string" }, "name": { "description": "Template name as stored in the config body. `null` if the current version has no `name` field.", "example": "Example Name", + "nullable": true, "type": "string" }, "updated_at": { @@ -72285,6 +79955,7 @@ "virtual_path": { "description": "Virtual filesystem path for this template config. `null` if not set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -72304,22 +79975,24 @@ "team": { "description": "ID of the team that owns this agent (`tem_...`). `null` if the agent is not team-scoped.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "template_upgrade_available": { "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`).", "example": true, + "nullable": true, "type": "boolean" }, "updated_at": { "description": "When the agent was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "user": { "description": "ID of the user that owns this agent (`usr_...`). `null` if the agent is not user-scoped.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" } }, @@ -72328,16 +80001,19 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "role": { "description": "The authenticated user's membership role in this thread, e.g. `\"owner\"`, `\"member\"`, or `\"viewer\"`. `null` if the user is not a member.", "example": "member", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the developer sandbox this thread is scoped to (`dsb_...`). `null` for production threads.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "settings": { @@ -72347,8 +80023,9 @@ }, "properties": { "agent_enabled": { - "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.", + "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.", "example": true, + "nullable": true, "type": "boolean" } }, @@ -72357,6 +80034,7 @@ "slug": { "description": "URL-safe slug for the thread, used in human-readable permalinks. `null` if not assigned.", "example": "example-slug", + "nullable": true, "type": "string" }, "sub_threads": { @@ -72365,8 +80043,10 @@ {} ], "items": { + "nullable": true, "type": "object" }, + "nullable": true, "type": "array" }, "tags": { @@ -72383,32 +80063,36 @@ "team": { "description": "ID of the team that owns this thread (`team_...`). `null` for user-owned or agent-owned threads.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "title": { "description": "Human-readable name of the thread. `null` if no title has been set.", "example": "Example Title", + "nullable": true, "type": "string" }, "ttl": { - "description": "Time-to-live in seconds after which the thread may be automatically cleaned up. `null` if the thread does not expire.", - "example": 3600, - "type": "integer" + "description": "Offset-free expiry timestamp after which the thread may be automatically cleaned up. `null` if the thread does not expire.", + "example": "2026-08-15T12:00:00", + "nullable": true, + "type": "string" }, "unread_count": { "description": "Number of messages in this thread that the authenticated user has not yet read. Present only when read-state enrichment is requested.", "example": 5, + "nullable": true, "type": "integer" }, "updated_at": { "description": "When the thread was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "user": { "description": "ID of the user who owns this thread (`usr_...`). `null` for team-owned or agent-owned threads.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "visibility": { @@ -72479,6 +80163,7 @@ "description": "An example description.", "is_unlisted": true, "key": "string", + "kind": "personal", "members": [ { "id": "string", @@ -72516,6 +80201,7 @@ "description": "An example description.", "is_unlisted": true, "key": "string", + "kind": "personal", "members": [ { "id": "string", @@ -72560,6 +80246,14 @@ "example": "string", "type": "string" }, + "kind": { + "description": "Optional behavioral subtype. `personal` is accepted only for a user-owned thread and limits membership to that user and agents currently owned by them. Mirror kinds remain server-derived and cannot be selected by callers.", + "enum": [ + "personal" + ], + "example": "personal", + "type": "string" + }, "members": { "description": "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.", "example": [ @@ -72648,8 +80342,9 @@ }, "properties": { "agent_enabled": { - "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.", + "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.", "example": true, + "nullable": true, "type": "boolean" } }, @@ -72716,6 +80411,334 @@ ] } }, + "/api/v1/users/{user}/tokens": { + "get": { + "description": "Returns all access tokens associated with the authenticated user, including\nactive and revoked tokens. Tokens are returned without their raw JWT values\n— the plaintext JWT is only available at creation time.\n\nThe caller must be the user identified by `user` and must present a\nfirst-party session (or a `full_access` access token).\n", + "operationId": "get_api_v1_users__user_tokens", + "parameters": [ + { + "description": "User ID (`usr_...`) or `me` for the authenticated user.", + "example": "string", + "in": "path", + "name": "user", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "description": "Collection of access tokens for the user.", + "example": { + "data": [ + { + "created_at": "2024-01-01T00:00:00Z", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "expires_at": "2024-01-01T00:00:00Z", + "id": "sat_0aBcDeFgHiJkLmNoPqRsTu", + "last_used_at": "2024-01-01T00:00:00Z", + "name": "Example Name", + "revoked_at": "2024-01-01T00:00:00Z", + "scopes": "string", + "token": "string" + } + ] + }, + "properties": { + "data": { + "description": "Array of access token objects. Raw JWT values are not included.", + "example": [ + { + "created_at": "2024-01-01T00:00:00Z", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "expires_at": "2024-01-01T00:00:00Z", + "id": "sat_0aBcDeFgHiJkLmNoPqRsTu", + "last_used_at": "2024-01-01T00:00:00Z", + "name": "Example Name", + "revoked_at": "2024-01-01T00:00:00Z", + "scopes": "string", + "token": "string" + } + ], + "items": { + "description": "A long-lived API credential associated with a system account, used to authenticate server-to-server requests.", + "example": { + "created_at": "2024-01-01T00:00:00Z", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "expires_at": "2024-01-01T00:00:00Z", + "id": "sat_0aBcDeFgHiJkLmNoPqRsTu", + "last_used_at": "2024-01-01T00:00:00Z", + "name": "Example Name", + "revoked_at": "2024-01-01T00:00:00Z", + "scopes": "string", + "token": "string" + }, + "properties": { + "created_at": { + "description": "When this token was created (ISO 8601).", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "type": "string" + }, + "created_by_agent_user": { + "description": "Agent user that minted this token (`usr_...`). `null` unless an agent minted it.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_developer": { + "description": "Developer account that minted this token (`dva_...`). `null` unless minted with a developer token.", + "example": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_org": { + "description": "Org of the principal that minted this token (`org_...`). `null` on legacy rows.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_team": { + "description": "Team that minted this token (`tem_...`). `null` unless minted as a team.", + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_user": { + "description": "User who minted this token (`usr_...`). Distinct from the token subject. `null` on legacy rows.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "expires_at": { + "description": "When the token expires. `null` on legacy rows that predate stored expiry.", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "nullable": true, + "type": "string" + }, + "id": { + "description": "Token ID (`sat_...`).", + "example": "sat_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "last_used_at": { + "description": "When this token was last used to authenticate a request. `null` if the token has never been used.", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "nullable": true, + "type": "string" + }, + "name": { + "description": "Human-readable label assigned to this token at creation time. `null` when no label was supplied.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "revoked_at": { + "description": "When this token was revoked. `null` if the token is still active.", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "nullable": true, + "type": "string" + }, + "scopes": { + "description": "Space-separated OAuth scopes stamped on the token. `null` on legacy rows; treat as `full_access`.", + "example": "string", + "nullable": true, + "type": "string" + }, + "token": { + "description": "Raw bearer token string. Present only in the response to the create request; never returned again after that.", + "example": "string", + "type": "string" + } + }, + "required": [ + "id" + ], + "type": "object" + }, + "type": "array" + } + }, + "required": [ + "data" + ], + "type": "object" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + } + }, + "summary": "List personal access tokens", + "x-auth": [ + "publishable_key", + "bearer" + ] + }, + "post": { + "description": "Issues a new long-lived access token for the authenticated user. The raw\nJWT is returned in the `token` field of the response exactly once and\ncannot be retrieved again — store it securely immediately after creation.\n\n`scopes` is optional. When omitted the token receives `full_access`.\nKnown catalog scopes (for example `profile`) restrict the token through\nthe same `ScopeGuard` used by OAuth.\n\n`expires_in_days` is optional and must be one of `7`, `30`, `60`, `90`,\nor `365`. When omitted the token lasts 30 days. Each user may hold at\nmost 50 active tokens; exceeding that limit returns 429.\n\nThe caller must be the user identified by `user` and must present a\nfirst-party session (or a `full_access` access token). A restricted\naccess token cannot mint another token.\n", + "operationId": "post_api_v1_users__user_tokens", + "parameters": [ + { + "description": "User ID (`usr_...`) or `me` for the authenticated user.", + "example": "string", + "in": "path", + "name": "user", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "example": { + "expires_in_days": 1, + "name": "Example Name", + "scopes": [ + "string" + ] + }, + "properties": { + "expires_in_days": { + "description": "Lifetime in days. One of `7`, `30`, `60`, `90`, or `365`. Defaults to `30`.", + "example": 1, + "type": "integer" + }, + "name": { + "description": "Human-readable label for the token (e.g. `\"Codex MCP\"`). Stored as metadata only.", + "example": "Example Name", + "type": "string" + }, + "scopes": { + "description": "Optional OAuth scopes to stamp on the token. Omit for `full_access`.", + "example": [ + "string" + ], + "items": { + "type": "string" + }, + "type": "array" + } + }, + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SystemAccessToken" + } + } + }, + "description": "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." + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "422": { + "description": "Invalid scopes, expiration, or user is a system user" + }, + "429": { + "description": "Token limit reached" + } + }, + "summary": "Create a personal access token", + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/users/{user}/tokens/{token}": { + "delete": { + "description": "Permanently revokes the specified access token belonging to the\nauthenticated user. Once revoked, the token is immediately rejected by\nall API endpoints and cannot be reinstated. The token record is retained\nand returned in the response with `revoked_at` populated.\n\nThe caller must be the user identified by `user` and must present a\nfirst-party session (or a `full_access` access token). Returns 404 if\nthe token does not exist or does not belong to the caller.\n", + "operationId": "delete_api_v1_users__user_tokens__token", + "parameters": [ + { + "description": "User ID (`usr_...`) or `me` for the authenticated user.", + "example": "string", + "in": "path", + "name": "user", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Access token ID (`sat_...`). Must belong to the authenticated user.", + "example": "string", + "in": "path", + "name": "token", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SystemAccessToken" + } + } + }, + "description": "The revoked access token. The `revoked_at` field is populated with the time of revocation." + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Token not found" + } + }, + "summary": "Revoke a personal access token", + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, "/api/v1/work_items": { "get": { "description": "Lists queued, claimed, and running external work yielded by durable workflows.\nThe top-level collection includes work for every agent the viewer can execute;\nthe agent-nested collection limits results to that agent. This discovery\nresponse never includes lease tokens. Use the agent claim endpoint to acquire\nnew work or resume a saved lease.\n", @@ -72852,115 +80875,249 @@ "description": "Invalid parameters; Validation failed" } }, - "summary": "Fail workflow work and route its durable execution", + "summary": "Fail workflow work and route its durable execution", + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/work_items/{work_item}/heartbeat": { + "post": { + "operationId": "post_api_v1_work_items__work_item_heartbeat", + "parameters": [ + { + "description": "Claimed or running work item ID.", + "example": "string", + "in": "path", + "name": "work_item", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "example": { + "lease_owner": "string", + "lease_seconds": 1 + }, + "properties": { + "lease_owner": { + "description": "Saved lease token.", + "example": "string", + "type": "string" + }, + "lease_seconds": { + "description": "Replacement lease duration from 15 through 3600 seconds. Defaults to 300.", + "example": 1, + "type": "integer" + } + }, + "required": [ + "lease_owner" + ], + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "204": { + "description": "No content" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "App-scoped token required. Use a token scoped to the target app.; Forbidden" + }, + "404": { + "description": "Agent not found; Resource not found" + }, + "409": { + "description": "Conflict" + }, + "422": { + "description": "Invalid parameters; Validation failed" + } + }, + "summary": "Extend a workflow work item lease", + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/work_items/{work_item}/start": { + "post": { + "operationId": "post_api_v1_work_items__work_item_start", + "parameters": [ + { + "description": "Claimed work item ID.", + "example": "string", + "in": "path", + "name": "work_item", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "example": { + "lease_owner": "string" + }, + "properties": { + "lease_owner": { + "description": "Saved lease token.", + "example": "string", + "type": "string" + } + }, + "required": [ + "lease_owner" + ], + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "204": { + "description": "No content" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "App-scoped token required. Use a token scoped to the target app.; Forbidden" + }, + "404": { + "description": "Agent not found; Resource not found" + }, + "409": { + "description": "Conflict" + }, + "422": { + "description": "Invalid parameters; Validation failed" + } + }, + "summary": "Mark claimed workflow work as running", + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/work_items/{work_item}/submit": { + "post": { + "description": "Atomically records the command completion, marks the work item succeeded,\nadvances the journal sequence, and enqueues the owning workflow continuation.\nRetrying the same lease and result is idempotent; a different result conflicts.\n", + "operationId": "post_api_v1_work_items__work_item_submit", + "parameters": [ + { + "description": "Claimed or running work item ID.", + "example": "string", + "in": "path", + "name": "work_item", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "example": { + "lease_owner": "string", + "result": {} + }, + "properties": { + "lease_owner": { + "description": "Saved lease token.", + "example": "string", + "type": "string" + }, + "result": { + "description": "JSON-serializable output returned to the workflow.", + "example": {}, + "type": "object" + } + }, + "required": [ + "lease_owner", + "result" + ], + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "204": { + "description": "No content" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "App-scoped token required. Use a token scoped to the target app.; Forbidden" + }, + "404": { + "description": "Agent not found; Resource not found" + }, + "409": { + "description": "Conflict" + }, + "422": { + "description": "Invalid parameters; Validation failed" + } + }, + "summary": "Submit workflow work output and wake its durable execution", "x-auth": [ "publishable_key", "bearer" ] } }, - "/api/v1/work_items/{work_item}/heartbeat": { + "/oauth/device/approve": { "post": { - "operationId": "post_api_v1_work_items__work_item_heartbeat", - "parameters": [ - { - "description": "Claimed or running work item ID.", - "example": "string", - "in": "path", - "name": "work_item", - "required": true, - "schema": { - "type": "string" - } - } - ], + "description": "Grants the pending device authorization identified by `user_code`, completing\nthe OAuth Device Authorization flow on behalf of the authenticated user. Once\napproved, the device can exchange the `device_code` for an access token.\n\nRequires a valid user session — the request must be authenticated as an end\nuser, not a machine client. The `user_code` must belong to a pending (not\nexpired, not already approved or denied) authorization associated with the\ncalling app.\n\nIf the requested scopes include a `thread`-scoped permission, you must supply\nthe `thread` parameter; omitting it returns a 400 with `error: \"invalid_scope\"`.\n", + "operationId": "post_oauth_device_approve", + "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "example": { - "lease_owner": "string", - "lease_seconds": 1 + "thread": "string", + "user_code": "string" }, "properties": { - "lease_owner": { - "description": "Saved lease token.", + "thread": { + "description": "Thread ID (`thr_...`) to bind to the authorization. Required when the requested scopes include a thread-scoped permission.", "example": "string", "type": "string" }, - "lease_seconds": { - "description": "Replacement lease duration from 15 through 3600 seconds. Defaults to 300.", - "example": 1, - "type": "integer" - } - }, - "required": [ - "lease_owner" - ], - "type": "object" - } - } - }, - "required": true - }, - "responses": { - "204": { - "description": "No content" - }, - "401": { - "description": "Unauthorized" - }, - "403": { - "description": "App-scoped token required. Use a token scoped to the target app.; Forbidden" - }, - "404": { - "description": "Agent not found; Resource not found" - }, - "409": { - "description": "Conflict" - }, - "422": { - "description": "Invalid parameters; Validation failed" - } - }, - "summary": "Extend a workflow work item lease", - "x-auth": [ - "publishable_key", - "bearer" - ] - } - }, - "/api/v1/work_items/{work_item}/start": { - "post": { - "operationId": "post_api_v1_work_items__work_item_start", - "parameters": [ - { - "description": "Claimed work item ID.", - "example": "string", - "in": "path", - "name": "work_item", - "required": true, - "schema": { - "type": "string" - } - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "example": { - "lease_owner": "string" - }, - "properties": { - "lease_owner": { - "description": "Saved lease token.", + "user_code": { + "description": "User-facing verification code shown on the device. Identifies the pending authorization to approve.", "example": "string", "type": "string" } }, "required": [ - "lease_owner" + "user_code" ], "type": "object" } @@ -72969,158 +81126,61 @@ "required": true }, "responses": { - "204": { - "description": "No content" + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeviceAuthorizationStatusResponse" + } + } + }, + "description": "Confirmation that the device authorization was approved. The `status` field will be `\"approved\"`." + }, + "400": { + "description": "Bad request" }, "401": { "description": "Unauthorized" - }, - "403": { - "description": "App-scoped token required. Use a token scoped to the target app.; Forbidden" - }, - "404": { - "description": "Agent not found; Resource not found" - }, - "409": { - "description": "Conflict" - }, - "422": { - "description": "Invalid parameters; Validation failed" } }, - "summary": "Mark claimed workflow work as running", - "x-auth": [ - "publishable_key", - "bearer" - ] + "summary": "Approve a device authorization request" } }, - "/api/v1/work_items/{work_item}/submit": { - "post": { - "description": "Atomically records the command completion, marks the work item succeeded,\nadvances the journal sequence, and enqueues the owning workflow continuation.\nRetrying the same lease and result is idempotent; a different result conflicts.\n", - "operationId": "post_api_v1_work_items__work_item_submit", + "/oauth/device/authorization": { + "get": { + "description": "Returns the client name, requested scopes, and expiration for a pending\ndevice authorization owned by the calling app. The caller must be an\nauthenticated user. This endpoint never approves the request.\n", + "operationId": "get_oauth_device_authorization", "parameters": [ { - "description": "Claimed or running work item ID.", + "description": "User-facing device authorization code.", "example": "string", - "in": "path", - "name": "work_item", + "in": "query", + "name": "code", "required": true, "schema": { "type": "string" } } ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "example": { - "lease_owner": "string", - "result": {} - }, - "properties": { - "lease_owner": { - "description": "Saved lease token.", - "example": "string", - "type": "string" - }, - "result": { - "description": "JSON-serializable output returned to the workflow.", - "example": {}, - "type": "object" - } - }, - "required": [ - "lease_owner", - "result" - ], - "type": "object" - } - } - }, - "required": true - }, - "responses": { - "204": { - "description": "No content" - }, - "401": { - "description": "Unauthorized" - }, - "403": { - "description": "App-scoped token required. Use a token scoped to the target app.; Forbidden" - }, - "404": { - "description": "Agent not found; Resource not found" - }, - "409": { - "description": "Conflict" - }, - "422": { - "description": "Invalid parameters; Validation failed" - } - }, - "summary": "Submit workflow work output and wake its durable execution", - "x-auth": [ - "publishable_key", - "bearer" - ] - } - }, - "/oauth/device/approve": { - "post": { - "description": "Grants the pending device authorization identified by `user_code`, completing\nthe OAuth Device Authorization flow on behalf of the authenticated user. Once\napproved, the device can exchange the `device_code` for an access token.\n\nRequires a valid user session — the request must be authenticated as an end\nuser, not a machine client. The `user_code` must belong to a pending (not\nexpired, not already approved or denied) authorization associated with the\ncalling app.\n\nIf the requested scopes include a `thread`-scoped permission, you must supply\nthe `thread` parameter; omitting it returns a 400 with `error: \"invalid_scope\"`.\n", - "operationId": "post_oauth_device_approve", - "parameters": [], - "requestBody": { - "content": { - "application/json": { - "schema": { - "example": { - "thread": "string", - "user_code": "string" - }, - "properties": { - "thread": { - "description": "Thread ID (`thr_...`) to bind to the authorization. Required when the requested scopes include a thread-scoped permission.", - "example": "string", - "type": "string" - }, - "user_code": { - "description": "User-facing verification code shown on the device. Identifies the pending authorization to approve.", - "example": "string", - "type": "string" - } - }, - "required": [ - "user_code" - ], - "type": "object" - } - } - }, - "required": true - }, "responses": { "200": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DeviceAuthorizationStatusResponse" + "$ref": "#/components/schemas/DeviceAuthorizationDetailsResponse" } } }, - "description": "Confirmation that the device authorization was approved. The `status` field will be `\"approved\"`." + "description": "Successful response" }, "400": { - "description": "Bad request" + "description": "Invalid or expired code" }, "401": { "description": "Unauthorized" } }, - "summary": "Approve a device authorization request" + "summary": "Inspect a pending device authorization" } }, "/oauth/device/authorize": { @@ -73614,7 +81674,7 @@ ] }, "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", - "created_at": "2024-01-01T00:00:00Z", + "created_at": "string", "default_model": "claude-3-7-sonnet-latest", "description": "An example description.", "email": "user@example.com", @@ -73762,7 +81822,7 @@ }, "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "template_upgrade_available": true, - "updated_at": "2024-01-01T00:00:00Z", + "updated_at": "string", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" }, "properties": { @@ -73796,6 +81856,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -73946,23 +82007,25 @@ }, "created_at": { "description": "When the agent was created (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "default_model": { "description": "Default LLM model identifier used by this agent when no model is specified at runtime (e.g. `\"claude-3-7-sonnet-latest\"`).", "example": "claude-3-7-sonnet-latest", + "nullable": true, "type": "string" }, "description": { "description": "Human-readable description of what the agent does. `null` if not set.", "example": "An example description.", + "nullable": true, "type": "string" }, "email": { "description": "Email address provisioned for this agent. `null` if email delivery is not configured.", "example": "user@example.com", + "nullable": true, "type": "string" }, "id": { @@ -73973,16 +82036,19 @@ "identity": { "description": "System-level identity prompt that shapes the agent's persona and behavior.", "example": "You are a helpful assistant that answers questions about ArchAstro products.", + "nullable": true, "type": "string" }, "last_applied_template_config": { "description": "ID of the AgentTemplate config (`cfg_...`) this agent was last provisioned or updated from. `null` for manually created agents.", "example": "cfg_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "lookup_key": { "description": "Stable, user-defined identifier for this agent within the application. Unique per app.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -74000,26 +82066,31 @@ "org": { "description": "ID of the organization this agent belongs to (`org_...`). `null` if the agent is not org-scoped.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_name": { "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.", "example": "Example Name", + "nullable": true, "type": "string" }, "originator": { "description": "Free-form label identifying the source or author that created this agent (e.g. a username or pipeline name).", "example": "deploy-pipeline", + "nullable": true, "type": "string" }, "phone_number": { "description": "Phone number provisioned for this agent. `null` if SMS is not configured.", "example": "+15555550123", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the sandbox environment this agent is scoped to (`dsb_...`). `null` in production deployments.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "source_solution": { @@ -74153,6 +82224,7 @@ "virtual_path": "string" } }, + "nullable": true, "properties": { "current_solution": { "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.", @@ -74227,13 +82299,13 @@ }, "created_at": { "description": "When the Solution config was first imported (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "events": { @@ -74249,6 +82321,7 @@ "image_url": { "description": "Absolute URL of the Solution's cover image — the bundled asset the body's `image:` field names. A stable, non-expiring capability URL (like `org_logo.url`), safe to hold in caches and OpenGraph tags; it 404s if the Solution stops declaring a cover. `null` when the Solution has no cover image, and always `null` for org-scoped rows — the permanent URL is minted for system-scope (catalog) Solutions only.", "example": "https://example.com", + "nullable": true, "type": "string" }, "kind": { @@ -74259,16 +82332,19 @@ "latest_solution": { "description": "When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "latest_version": { "description": "When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", "example": "1.0.0", + "nullable": true, "type": "string" }, "lookup_key": { "description": "The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -74281,11 +82357,13 @@ "name": { "description": "Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "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.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_logo": { @@ -74299,40 +82377,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -74341,11 +82427,13 @@ "org_name": { "description": "Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_slug": { "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.", "example": "example-slug", + "nullable": true, "type": "string" }, "owners": { @@ -74361,6 +82449,7 @@ "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "screenshot_urls": { @@ -74376,11 +82465,13 @@ "solution_id": { "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.", "example": "01234567-89ab-cdef-0123-456789abcdef", + "nullable": true, "type": "string" }, "solution_version": { "description": "Semver string declared in the Solution body (e.g. `\"1.2.0\"`). `null` when the body does not declare a version.", "example": "1.2.0", + "nullable": true, "type": "string" }, "tag_keys": { @@ -74396,6 +82487,7 @@ "template_kind": { "description": "Wrapped template kind — `\"AgentTemplate\"`, `\"AutomationTemplate\"`, `\"AgentRoutineTemplate\"`, `\"AgentToolTemplate\"`, `\"AgentComputerTemplate\"`, or `\"SolutionTemplateRef\"` for ref-mode bundles.", "example": "AgentTemplate", + "nullable": true, "type": "string" }, "templates": { @@ -74428,6 +82520,7 @@ "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "details": { @@ -74435,6 +82528,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -74459,12 +82553,13 @@ }, "properties": { "automation_type": { - "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`).", + "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", "example": "string", + "nullable": true, "type": "string" }, "invoke_contract": { - "description": "Schema-driven payload and participant inputs for an invoked automation. Used by installation clients to collect locked prefills before provisioning.", + "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.", "example": { "input_schema": {}, "participants": [ @@ -74480,10 +82575,12 @@ "payload": {} } }, + "nullable": true, "properties": { "input_schema": { "description": "JSON Schema validated against the whole invoke payload, from the automation's `input_schema_config`. `null` when none is configured.", "example": {}, + "nullable": true, "type": "object" }, "participants": { @@ -74504,10 +82601,12 @@ "required": true, "type": "agent_user" }, + "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", "example": "An example description.", + "nullable": true, "type": "string" }, "name": { @@ -74533,6 +82632,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -74581,11 +82681,13 @@ "display_name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "id": { "description": "Template config ID (`cfg_...`). `null` for inline-only templates.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "kind": { @@ -74596,21 +82698,25 @@ "lookup_key": { "description": "Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", "example": "string", + "nullable": true, "type": "string" }, "name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "virtual_path": { "description": "Stable virtual path assigned to the template config. `null` when no virtual path was set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -74623,8 +82729,7 @@ }, "updated_at": { "description": "When the Solution config was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "upgrade_available": { @@ -74635,6 +82740,7 @@ "virtual_path": { "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.", "example": "string", + "nullable": true, "type": "string" } }, @@ -74720,13 +82826,13 @@ }, "created_at": { "description": "When the Solution config was first imported (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "events": { @@ -74742,6 +82848,7 @@ "image_url": { "description": "Absolute URL of the Solution's cover image — the bundled asset the body's `image:` field names. A stable, non-expiring capability URL (like `org_logo.url`), safe to hold in caches and OpenGraph tags; it 404s if the Solution stops declaring a cover. `null` when the Solution has no cover image, and always `null` for org-scoped rows — the permanent URL is minted for system-scope (catalog) Solutions only.", "example": "https://example.com", + "nullable": true, "type": "string" }, "kind": { @@ -74752,16 +82859,19 @@ "latest_solution": { "description": "When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "latest_version": { "description": "When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", "example": "1.0.0", + "nullable": true, "type": "string" }, "lookup_key": { "description": "The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -74774,11 +82884,13 @@ "name": { "description": "Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "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.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_logo": { @@ -74792,40 +82904,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -74834,11 +82954,13 @@ "org_name": { "description": "Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_slug": { "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.", "example": "example-slug", + "nullable": true, "type": "string" }, "owners": { @@ -74854,6 +82976,7 @@ "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "screenshot_urls": { @@ -74869,11 +82992,13 @@ "solution_id": { "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.", "example": "01234567-89ab-cdef-0123-456789abcdef", + "nullable": true, "type": "string" }, "solution_version": { "description": "Semver string declared in the Solution body (e.g. `\"1.2.0\"`). `null` when the body does not declare a version.", "example": "1.2.0", + "nullable": true, "type": "string" }, "tag_keys": { @@ -74889,6 +83014,7 @@ "template_kind": { "description": "Wrapped template kind — `\"AgentTemplate\"`, `\"AutomationTemplate\"`, `\"AgentRoutineTemplate\"`, `\"AgentToolTemplate\"`, `\"AgentComputerTemplate\"`, or `\"SolutionTemplateRef\"` for ref-mode bundles.", "example": "AgentTemplate", + "nullable": true, "type": "string" }, "templates": { @@ -74921,6 +83047,7 @@ "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "details": { @@ -74928,6 +83055,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -74952,12 +83080,13 @@ }, "properties": { "automation_type": { - "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`).", + "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", "example": "string", + "nullable": true, "type": "string" }, "invoke_contract": { - "description": "Schema-driven payload and participant inputs for an invoked automation. Used by installation clients to collect locked prefills before provisioning.", + "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.", "example": { "input_schema": {}, "participants": [ @@ -74973,10 +83102,12 @@ "payload": {} } }, + "nullable": true, "properties": { "input_schema": { "description": "JSON Schema validated against the whole invoke payload, from the automation's `input_schema_config`. `null` when none is configured.", "example": {}, + "nullable": true, "type": "object" }, "participants": { @@ -74997,10 +83128,12 @@ "required": true, "type": "agent_user" }, + "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", "example": "An example description.", + "nullable": true, "type": "string" }, "name": { @@ -75026,6 +83159,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -75074,11 +83208,13 @@ "display_name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "id": { "description": "Template config ID (`cfg_...`). `null` for inline-only templates.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "kind": { @@ -75089,21 +83225,25 @@ "lookup_key": { "description": "Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", "example": "string", + "nullable": true, "type": "string" }, "name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "virtual_path": { "description": "Stable virtual path assigned to the template config. `null` when no virtual path was set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -75116,8 +83256,7 @@ }, "updated_at": { "description": "When the Solution config was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "upgrade_available": { @@ -75128,6 +83267,7 @@ "virtual_path": { "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.", "example": "string", + "nullable": true, "type": "string" } }, @@ -75163,11 +83303,13 @@ "description": { "description": "Description of the template from the config body. `null` if the current version has no `description` field.", "example": "An example description.", + "nullable": true, "type": "string" }, "display_name": { "description": "Human-readable display name from the config body. `null` if the current version has no `display_name` field.", "example": "Example Name", + "nullable": true, "type": "string" }, "id": { @@ -75183,11 +83325,13 @@ "lookup_key": { "description": "Stable lookup key assigned to this template config. `null` if no lookup key is set.", "example": "string", + "nullable": true, "type": "string" }, "name": { "description": "Template name as stored in the config body. `null` if the current version has no `name` field.", "example": "Example Name", + "nullable": true, "type": "string" }, "updated_at": { @@ -75199,6 +83343,7 @@ "virtual_path": { "description": "Virtual filesystem path for this template config. `null` if not set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -75218,22 +83363,24 @@ "team": { "description": "ID of the team that owns this agent (`tem_...`). `null` if the agent is not team-scoped.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "template_upgrade_available": { "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`).", "example": true, + "nullable": true, "type": "boolean" }, "updated_at": { "description": "When the agent was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "user": { "description": "ID of the user that owns this agent (`usr_...`). `null` if the agent is not user-scoped.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" } }, @@ -75356,6 +83503,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -75366,6 +83518,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" }, @@ -75373,21 +83526,55 @@ "alias": { "description": "Short handle or alias for the user. `null` if not set.", "example": "jdoe", + "nullable": true, "type": "string" }, "app": { "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.", "example": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "app_name": { "description": "Display name of the user's app. `null` when the app association was not preloaded by the caller.", "example": "Example Name", + "nullable": true, + "type": "string" + }, + "created_by_agent_user": { + "description": "Agent user that created this account (`usr_...`). `null` unless an agent created it.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_developer": { + "description": "Developer account that created this user (`dva_...`). `null` unless created via a developer token.", + "example": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_org": { + "description": "Org of the principal that created this user (`org_...`). `null` on legacy rows.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_team": { + "description": "Team that created this user (`tem_...`). `null` unless created as a team.", + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_user": { + "description": "User who created this account (`usr_...`). `null` on self-signup or legacy rows.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "email": { "description": "Email address of the user.", "example": "user@example.com", + "nullable": true, "type": "string" }, "id": { @@ -75410,31 +83597,43 @@ "name": { "description": "Full display name of the user. `null` if the user has not set a name.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "description": "ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_name": { "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.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_role": { "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.", "example": "member", + "nullable": true, + "type": "string" + }, + "org_slug": { + "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.", + "example": "example-slug", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "sandbox_name": { "description": "Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.", "example": "Example Name", + "nullable": true, "type": "string" } }, @@ -76171,6 +84370,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -76181,6 +84385,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -76320,7 +84525,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" } ], @@ -76522,7 +84727,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "participant": [ @@ -76533,6 +84738,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -76543,6 +84753,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -76748,7 +84959,7 @@ ], "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "title": "Example Title", - "ttl": 3600, + "ttl": "2026-08-15T12:00:00", "unread_count": 5, "updated_at": "2024-01-01T00:00:00Z", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", @@ -76952,7 +85163,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "participant": [ @@ -76963,6 +85174,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -76973,6 +85189,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -77178,7 +85395,7 @@ ], "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "title": "Example Title", - "ttl": 3600, + "ttl": "2026-08-15T12:00:00", "unread_count": 5, "updated_at": "2024-01-01T00:00:00Z", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", @@ -77562,6 +85779,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -77572,6 +85794,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -77711,7 +85934,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" } ], @@ -77913,7 +86136,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "participant": [ @@ -77924,6 +86147,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -77934,6 +86162,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -78139,7 +86368,7 @@ ], "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "title": "Example Title", - "ttl": 3600, + "ttl": "2026-08-15T12:00:00", "unread_count": 5, "updated_at": "2024-01-01T00:00:00Z", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", @@ -78366,6 +86595,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -78516,23 +86746,25 @@ }, "created_at": { "description": "When the agent was created (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "default_model": { "description": "Default LLM model identifier used by this agent when no model is specified at runtime (e.g. `\"claude-3-7-sonnet-latest\"`).", "example": "claude-3-7-sonnet-latest", + "nullable": true, "type": "string" }, "description": { "description": "Human-readable description of what the agent does. `null` if not set.", "example": "An example description.", + "nullable": true, "type": "string" }, "email": { "description": "Email address provisioned for this agent. `null` if email delivery is not configured.", "example": "user@example.com", + "nullable": true, "type": "string" }, "id": { @@ -78543,16 +86775,19 @@ "identity": { "description": "System-level identity prompt that shapes the agent's persona and behavior.", "example": "You are a helpful assistant that answers questions about ArchAstro products.", + "nullable": true, "type": "string" }, "last_applied_template_config": { "description": "ID of the AgentTemplate config (`cfg_...`) this agent was last provisioned or updated from. `null` for manually created agents.", "example": "cfg_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "lookup_key": { "description": "Stable, user-defined identifier for this agent within the application. Unique per app.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -78570,26 +86805,31 @@ "org": { "description": "ID of the organization this agent belongs to (`org_...`). `null` if the agent is not org-scoped.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_name": { "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.", "example": "Example Name", + "nullable": true, "type": "string" }, "originator": { "description": "Free-form label identifying the source or author that created this agent (e.g. a username or pipeline name).", "example": "deploy-pipeline", + "nullable": true, "type": "string" }, "phone_number": { "description": "Phone number provisioned for this agent. `null` if SMS is not configured.", "example": "+15555550123", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the sandbox environment this agent is scoped to (`dsb_...`). `null` in production deployments.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "source_solution": { @@ -78723,6 +86963,7 @@ "virtual_path": "string" } }, + "nullable": true, "properties": { "current_solution": { "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.", @@ -78797,13 +87038,13 @@ }, "created_at": { "description": "When the Solution config was first imported (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "events": { @@ -78819,6 +87060,7 @@ "image_url": { "description": "Absolute URL of the Solution's cover image — the bundled asset the body's `image:` field names. A stable, non-expiring capability URL (like `org_logo.url`), safe to hold in caches and OpenGraph tags; it 404s if the Solution stops declaring a cover. `null` when the Solution has no cover image, and always `null` for org-scoped rows — the permanent URL is minted for system-scope (catalog) Solutions only.", "example": "https://example.com", + "nullable": true, "type": "string" }, "kind": { @@ -78829,16 +87071,19 @@ "latest_solution": { "description": "When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "latest_version": { "description": "When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", "example": "1.0.0", + "nullable": true, "type": "string" }, "lookup_key": { "description": "The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -78851,11 +87096,13 @@ "name": { "description": "Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "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.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_logo": { @@ -78869,40 +87116,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -78911,11 +87166,13 @@ "org_name": { "description": "Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_slug": { "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.", "example": "example-slug", + "nullable": true, "type": "string" }, "owners": { @@ -78931,6 +87188,7 @@ "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "screenshot_urls": { @@ -78946,11 +87204,13 @@ "solution_id": { "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.", "example": "01234567-89ab-cdef-0123-456789abcdef", + "nullable": true, "type": "string" }, "solution_version": { "description": "Semver string declared in the Solution body (e.g. `\"1.2.0\"`). `null` when the body does not declare a version.", "example": "1.2.0", + "nullable": true, "type": "string" }, "tag_keys": { @@ -78966,6 +87226,7 @@ "template_kind": { "description": "Wrapped template kind — `\"AgentTemplate\"`, `\"AutomationTemplate\"`, `\"AgentRoutineTemplate\"`, `\"AgentToolTemplate\"`, `\"AgentComputerTemplate\"`, or `\"SolutionTemplateRef\"` for ref-mode bundles.", "example": "AgentTemplate", + "nullable": true, "type": "string" }, "templates": { @@ -78998,6 +87259,7 @@ "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "details": { @@ -79005,6 +87267,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -79029,12 +87292,13 @@ }, "properties": { "automation_type": { - "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`).", + "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", "example": "string", + "nullable": true, "type": "string" }, "invoke_contract": { - "description": "Schema-driven payload and participant inputs for an invoked automation. Used by installation clients to collect locked prefills before provisioning.", + "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.", "example": { "input_schema": {}, "participants": [ @@ -79050,10 +87314,12 @@ "payload": {} } }, + "nullable": true, "properties": { "input_schema": { "description": "JSON Schema validated against the whole invoke payload, from the automation's `input_schema_config`. `null` when none is configured.", "example": {}, + "nullable": true, "type": "object" }, "participants": { @@ -79074,10 +87340,12 @@ "required": true, "type": "agent_user" }, + "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", "example": "An example description.", + "nullable": true, "type": "string" }, "name": { @@ -79103,6 +87371,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -79151,11 +87420,13 @@ "display_name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "id": { "description": "Template config ID (`cfg_...`). `null` for inline-only templates.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "kind": { @@ -79166,21 +87437,25 @@ "lookup_key": { "description": "Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", "example": "string", + "nullable": true, "type": "string" }, "name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "virtual_path": { "description": "Stable virtual path assigned to the template config. `null` when no virtual path was set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -79193,8 +87468,7 @@ }, "updated_at": { "description": "When the Solution config was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "upgrade_available": { @@ -79205,6 +87479,7 @@ "virtual_path": { "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.", "example": "string", + "nullable": true, "type": "string" } }, @@ -79290,13 +87565,13 @@ }, "created_at": { "description": "When the Solution config was first imported (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "events": { @@ -79312,6 +87587,7 @@ "image_url": { "description": "Absolute URL of the Solution's cover image — the bundled asset the body's `image:` field names. A stable, non-expiring capability URL (like `org_logo.url`), safe to hold in caches and OpenGraph tags; it 404s if the Solution stops declaring a cover. `null` when the Solution has no cover image, and always `null` for org-scoped rows — the permanent URL is minted for system-scope (catalog) Solutions only.", "example": "https://example.com", + "nullable": true, "type": "string" }, "kind": { @@ -79322,16 +87598,19 @@ "latest_solution": { "description": "When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "latest_version": { "description": "When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", "example": "1.0.0", + "nullable": true, "type": "string" }, "lookup_key": { "description": "The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -79344,11 +87623,13 @@ "name": { "description": "Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "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.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_logo": { @@ -79362,40 +87643,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -79404,11 +87693,13 @@ "org_name": { "description": "Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_slug": { "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.", "example": "example-slug", + "nullable": true, "type": "string" }, "owners": { @@ -79424,6 +87715,7 @@ "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "screenshot_urls": { @@ -79439,11 +87731,13 @@ "solution_id": { "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.", "example": "01234567-89ab-cdef-0123-456789abcdef", + "nullable": true, "type": "string" }, "solution_version": { "description": "Semver string declared in the Solution body (e.g. `\"1.2.0\"`). `null` when the body does not declare a version.", "example": "1.2.0", + "nullable": true, "type": "string" }, "tag_keys": { @@ -79459,6 +87753,7 @@ "template_kind": { "description": "Wrapped template kind — `\"AgentTemplate\"`, `\"AutomationTemplate\"`, `\"AgentRoutineTemplate\"`, `\"AgentToolTemplate\"`, `\"AgentComputerTemplate\"`, or `\"SolutionTemplateRef\"` for ref-mode bundles.", "example": "AgentTemplate", + "nullable": true, "type": "string" }, "templates": { @@ -79491,6 +87786,7 @@ "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "details": { @@ -79498,6 +87794,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -79522,12 +87819,13 @@ }, "properties": { "automation_type": { - "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`).", + "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", "example": "string", + "nullable": true, "type": "string" }, "invoke_contract": { - "description": "Schema-driven payload and participant inputs for an invoked automation. Used by installation clients to collect locked prefills before provisioning.", + "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.", "example": { "input_schema": {}, "participants": [ @@ -79543,10 +87841,12 @@ "payload": {} } }, + "nullable": true, "properties": { "input_schema": { "description": "JSON Schema validated against the whole invoke payload, from the automation's `input_schema_config`. `null` when none is configured.", "example": {}, + "nullable": true, "type": "object" }, "participants": { @@ -79567,10 +87867,12 @@ "required": true, "type": "agent_user" }, + "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", "example": "An example description.", + "nullable": true, "type": "string" }, "name": { @@ -79596,6 +87898,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -79644,11 +87947,13 @@ "display_name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "id": { "description": "Template config ID (`cfg_...`). `null` for inline-only templates.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "kind": { @@ -79659,21 +87964,25 @@ "lookup_key": { "description": "Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", "example": "string", + "nullable": true, "type": "string" }, "name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "virtual_path": { "description": "Stable virtual path assigned to the template config. `null` when no virtual path was set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -79686,8 +87995,7 @@ }, "updated_at": { "description": "When the Solution config was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "upgrade_available": { @@ -79698,6 +88006,7 @@ "virtual_path": { "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.", "example": "string", + "nullable": true, "type": "string" } }, @@ -79733,11 +88042,13 @@ "description": { "description": "Description of the template from the config body. `null` if the current version has no `description` field.", "example": "An example description.", + "nullable": true, "type": "string" }, "display_name": { "description": "Human-readable display name from the config body. `null` if the current version has no `display_name` field.", "example": "Example Name", + "nullable": true, "type": "string" }, "id": { @@ -79753,11 +88064,13 @@ "lookup_key": { "description": "Stable lookup key assigned to this template config. `null` if no lookup key is set.", "example": "string", + "nullable": true, "type": "string" }, "name": { "description": "Template name as stored in the config body. `null` if the current version has no `name` field.", "example": "Example Name", + "nullable": true, "type": "string" }, "updated_at": { @@ -79769,6 +88082,7 @@ "virtual_path": { "description": "Virtual filesystem path for this template config. `null` if not set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -79788,22 +88102,24 @@ "team": { "description": "ID of the team that owns this agent (`tem_...`). `null` if the agent is not team-scoped.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "template_upgrade_available": { "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`).", "example": true, + "nullable": true, "type": "boolean" }, "updated_at": { "description": "When the agent was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "user": { "description": "ID of the user that owns this agent (`usr_...`). `null` if the agent is not user-scoped.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" } }, @@ -80013,6 +88329,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -80023,6 +88344,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -80218,6 +88540,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -80228,6 +88555,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -80447,6 +88775,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -80597,23 +88926,25 @@ }, "created_at": { "description": "When the agent was created (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "default_model": { "description": "Default LLM model identifier used by this agent when no model is specified at runtime (e.g. `\"claude-3-7-sonnet-latest\"`).", "example": "claude-3-7-sonnet-latest", + "nullable": true, "type": "string" }, "description": { "description": "Human-readable description of what the agent does. `null` if not set.", "example": "An example description.", + "nullable": true, "type": "string" }, "email": { "description": "Email address provisioned for this agent. `null` if email delivery is not configured.", "example": "user@example.com", + "nullable": true, "type": "string" }, "id": { @@ -80624,16 +88955,19 @@ "identity": { "description": "System-level identity prompt that shapes the agent's persona and behavior.", "example": "You are a helpful assistant that answers questions about ArchAstro products.", + "nullable": true, "type": "string" }, "last_applied_template_config": { "description": "ID of the AgentTemplate config (`cfg_...`) this agent was last provisioned or updated from. `null` for manually created agents.", "example": "cfg_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "lookup_key": { "description": "Stable, user-defined identifier for this agent within the application. Unique per app.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -80651,26 +88985,31 @@ "org": { "description": "ID of the organization this agent belongs to (`org_...`). `null` if the agent is not org-scoped.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_name": { "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.", "example": "Example Name", + "nullable": true, "type": "string" }, "originator": { "description": "Free-form label identifying the source or author that created this agent (e.g. a username or pipeline name).", "example": "deploy-pipeline", + "nullable": true, "type": "string" }, "phone_number": { "description": "Phone number provisioned for this agent. `null` if SMS is not configured.", "example": "+15555550123", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the sandbox environment this agent is scoped to (`dsb_...`). `null` in production deployments.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "source_solution": { @@ -80804,6 +89143,7 @@ "virtual_path": "string" } }, + "nullable": true, "properties": { "current_solution": { "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.", @@ -80878,13 +89218,13 @@ }, "created_at": { "description": "When the Solution config was first imported (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "events": { @@ -80900,6 +89240,7 @@ "image_url": { "description": "Absolute URL of the Solution's cover image — the bundled asset the body's `image:` field names. A stable, non-expiring capability URL (like `org_logo.url`), safe to hold in caches and OpenGraph tags; it 404s if the Solution stops declaring a cover. `null` when the Solution has no cover image, and always `null` for org-scoped rows — the permanent URL is minted for system-scope (catalog) Solutions only.", "example": "https://example.com", + "nullable": true, "type": "string" }, "kind": { @@ -80910,16 +89251,19 @@ "latest_solution": { "description": "When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "latest_version": { "description": "When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", "example": "1.0.0", + "nullable": true, "type": "string" }, "lookup_key": { "description": "The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -80932,11 +89276,13 @@ "name": { "description": "Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "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.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_logo": { @@ -80950,40 +89296,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -80992,11 +89346,13 @@ "org_name": { "description": "Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_slug": { "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.", "example": "example-slug", + "nullable": true, "type": "string" }, "owners": { @@ -81012,6 +89368,7 @@ "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "screenshot_urls": { @@ -81027,11 +89384,13 @@ "solution_id": { "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.", "example": "01234567-89ab-cdef-0123-456789abcdef", + "nullable": true, "type": "string" }, "solution_version": { "description": "Semver string declared in the Solution body (e.g. `\"1.2.0\"`). `null` when the body does not declare a version.", "example": "1.2.0", + "nullable": true, "type": "string" }, "tag_keys": { @@ -81047,6 +89406,7 @@ "template_kind": { "description": "Wrapped template kind — `\"AgentTemplate\"`, `\"AutomationTemplate\"`, `\"AgentRoutineTemplate\"`, `\"AgentToolTemplate\"`, `\"AgentComputerTemplate\"`, or `\"SolutionTemplateRef\"` for ref-mode bundles.", "example": "AgentTemplate", + "nullable": true, "type": "string" }, "templates": { @@ -81079,6 +89439,7 @@ "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "details": { @@ -81086,6 +89447,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -81110,12 +89472,13 @@ }, "properties": { "automation_type": { - "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`).", + "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", "example": "string", + "nullable": true, "type": "string" }, "invoke_contract": { - "description": "Schema-driven payload and participant inputs for an invoked automation. Used by installation clients to collect locked prefills before provisioning.", + "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.", "example": { "input_schema": {}, "participants": [ @@ -81131,10 +89494,12 @@ "payload": {} } }, + "nullable": true, "properties": { "input_schema": { "description": "JSON Schema validated against the whole invoke payload, from the automation's `input_schema_config`. `null` when none is configured.", "example": {}, + "nullable": true, "type": "object" }, "participants": { @@ -81155,10 +89520,12 @@ "required": true, "type": "agent_user" }, + "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", "example": "An example description.", + "nullable": true, "type": "string" }, "name": { @@ -81184,6 +89551,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -81232,11 +89600,13 @@ "display_name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "id": { "description": "Template config ID (`cfg_...`). `null` for inline-only templates.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "kind": { @@ -81247,21 +89617,25 @@ "lookup_key": { "description": "Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", "example": "string", + "nullable": true, "type": "string" }, "name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "virtual_path": { "description": "Stable virtual path assigned to the template config. `null` when no virtual path was set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -81274,8 +89648,7 @@ }, "updated_at": { "description": "When the Solution config was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "upgrade_available": { @@ -81286,6 +89659,7 @@ "virtual_path": { "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.", "example": "string", + "nullable": true, "type": "string" } }, @@ -81371,13 +89745,13 @@ }, "created_at": { "description": "When the Solution config was first imported (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "events": { @@ -81393,6 +89767,7 @@ "image_url": { "description": "Absolute URL of the Solution's cover image — the bundled asset the body's `image:` field names. A stable, non-expiring capability URL (like `org_logo.url`), safe to hold in caches and OpenGraph tags; it 404s if the Solution stops declaring a cover. `null` when the Solution has no cover image, and always `null` for org-scoped rows — the permanent URL is minted for system-scope (catalog) Solutions only.", "example": "https://example.com", + "nullable": true, "type": "string" }, "kind": { @@ -81403,16 +89778,19 @@ "latest_solution": { "description": "When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "latest_version": { "description": "When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", "example": "1.0.0", + "nullable": true, "type": "string" }, "lookup_key": { "description": "The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -81425,11 +89803,13 @@ "name": { "description": "Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "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.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_logo": { @@ -81443,40 +89823,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -81485,11 +89873,13 @@ "org_name": { "description": "Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_slug": { "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.", "example": "example-slug", + "nullable": true, "type": "string" }, "owners": { @@ -81505,6 +89895,7 @@ "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "screenshot_urls": { @@ -81520,11 +89911,13 @@ "solution_id": { "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.", "example": "01234567-89ab-cdef-0123-456789abcdef", + "nullable": true, "type": "string" }, "solution_version": { "description": "Semver string declared in the Solution body (e.g. `\"1.2.0\"`). `null` when the body does not declare a version.", "example": "1.2.0", + "nullable": true, "type": "string" }, "tag_keys": { @@ -81540,6 +89933,7 @@ "template_kind": { "description": "Wrapped template kind — `\"AgentTemplate\"`, `\"AutomationTemplate\"`, `\"AgentRoutineTemplate\"`, `\"AgentToolTemplate\"`, `\"AgentComputerTemplate\"`, or `\"SolutionTemplateRef\"` for ref-mode bundles.", "example": "AgentTemplate", + "nullable": true, "type": "string" }, "templates": { @@ -81572,6 +89966,7 @@ "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "details": { @@ -81579,6 +89974,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -81603,12 +89999,13 @@ }, "properties": { "automation_type": { - "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`).", + "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", "example": "string", + "nullable": true, "type": "string" }, "invoke_contract": { - "description": "Schema-driven payload and participant inputs for an invoked automation. Used by installation clients to collect locked prefills before provisioning.", + "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.", "example": { "input_schema": {}, "participants": [ @@ -81624,10 +90021,12 @@ "payload": {} } }, + "nullable": true, "properties": { "input_schema": { "description": "JSON Schema validated against the whole invoke payload, from the automation's `input_schema_config`. `null` when none is configured.", "example": {}, + "nullable": true, "type": "object" }, "participants": { @@ -81648,10 +90047,12 @@ "required": true, "type": "agent_user" }, + "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", "example": "An example description.", + "nullable": true, "type": "string" }, "name": { @@ -81677,6 +90078,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -81725,11 +90127,13 @@ "display_name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "id": { "description": "Template config ID (`cfg_...`). `null` for inline-only templates.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "kind": { @@ -81740,21 +90144,25 @@ "lookup_key": { "description": "Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", "example": "string", + "nullable": true, "type": "string" }, "name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "virtual_path": { "description": "Stable virtual path assigned to the template config. `null` when no virtual path was set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -81767,8 +90175,7 @@ }, "updated_at": { "description": "When the Solution config was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "upgrade_available": { @@ -81779,6 +90186,7 @@ "virtual_path": { "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.", "example": "string", + "nullable": true, "type": "string" } }, @@ -81814,11 +90222,13 @@ "description": { "description": "Description of the template from the config body. `null` if the current version has no `description` field.", "example": "An example description.", + "nullable": true, "type": "string" }, "display_name": { "description": "Human-readable display name from the config body. `null` if the current version has no `display_name` field.", "example": "Example Name", + "nullable": true, "type": "string" }, "id": { @@ -81834,11 +90244,13 @@ "lookup_key": { "description": "Stable lookup key assigned to this template config. `null` if no lookup key is set.", "example": "string", + "nullable": true, "type": "string" }, "name": { "description": "Template name as stored in the config body. `null` if the current version has no `name` field.", "example": "Example Name", + "nullable": true, "type": "string" }, "updated_at": { @@ -81850,6 +90262,7 @@ "virtual_path": { "description": "Virtual filesystem path for this template config. `null` if not set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -81869,22 +90282,24 @@ "team": { "description": "ID of the team that owns this agent (`tem_...`). `null` if the agent is not team-scoped.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "template_upgrade_available": { "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`).", "example": true, + "nullable": true, "type": "boolean" }, "updated_at": { "description": "When the agent was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "user": { "description": "ID of the user that owns this agent (`usr_...`). `null` if the agent is not user-scoped.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" } }, @@ -81909,6 +90324,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -81919,6 +90339,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" }, @@ -81926,21 +90347,55 @@ "alias": { "description": "Short handle or alias for the user. `null` if not set.", "example": "jdoe", + "nullable": true, "type": "string" }, "app": { "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.", "example": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "app_name": { "description": "Display name of the user's app. `null` when the app association was not preloaded by the caller.", "example": "Example Name", + "nullable": true, + "type": "string" + }, + "created_by_agent_user": { + "description": "Agent user that created this account (`usr_...`). `null` unless an agent created it.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_developer": { + "description": "Developer account that created this user (`dva_...`). `null` unless created via a developer token.", + "example": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_org": { + "description": "Org of the principal that created this user (`org_...`). `null` on legacy rows.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_team": { + "description": "Team that created this user (`tem_...`). `null` unless created as a team.", + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_user": { + "description": "User who created this account (`usr_...`). `null` on self-signup or legacy rows.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "email": { "description": "Email address of the user.", "example": "user@example.com", + "nullable": true, "type": "string" }, "id": { @@ -81963,31 +90418,43 @@ "name": { "description": "Full display name of the user. `null` if the user has not set a name.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "description": "ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_name": { "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.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_role": { "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.", "example": "member", + "nullable": true, + "type": "string" + }, + "org_slug": { + "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.", + "example": "example-slug", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "sandbox_name": { "description": "Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.", "example": "Example Name", + "nullable": true, "type": "string" } }, @@ -82140,7 +90607,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" } ], @@ -82247,7 +90714,7 @@ ], "branched_thread": "string", "content": "Hello, how can I help you today?", - "created_at": "2024-01-01T00:00:00Z", + "created_at": "string", "has_replies": true, "id": "msg_0aBcDeFgHiJkLmNoPqRsTu", "idempotency_key": "01234567-89ab-cdef-0123-456789abcdef", @@ -82406,7 +90873,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "root_message_id": "string", @@ -82414,7 +90881,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "properties": { @@ -82448,6 +90915,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -82629,16 +91097,19 @@ "alias": { "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", "example": "alice", + "nullable": true, "type": "string" }, "id": { "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "nullable": true, "type": "string" }, "name": { "description": "Display name of the actor shown in the UI. `null` if no name is set.", "example": "Example Name", + "nullable": true, "type": "string" }, "profile_picture": { @@ -82652,40 +91123,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -82699,6 +91178,7 @@ "agent": { "description": "ID of the agent user that sent this message (`agi_...`). `null` for messages sent by human users.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "agent_mode": { @@ -82708,6 +91188,7 @@ "embedded" ], "example": "cli", + "nullable": true, "type": "string" }, "attachments": { @@ -82820,21 +91301,25 @@ "content_type": { "description": "MIME type of the attached file, e.g. `\"image/png\"` or `\"application/pdf\"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.", "example": "application/json", + "nullable": true, "type": "string" }, "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "filename": { "description": "Original filename of the attached file, e.g. `\"report.pdf\"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.", "example": "string", + "nullable": true, "type": "string" }, "height": { "description": "Height in pixels of the media item. Present on `media` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "id": { @@ -82845,6 +91330,7 @@ "image_height": { "description": "Height in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "image_source": { @@ -82858,40 +91344,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -82900,31 +91394,35 @@ "image_url": { "description": "URL of the preview image extracted from the scraped page. Present on `scraped_link` type only. `null` otherwise.", "example": "https://example.com", + "nullable": true, "type": "string" }, "image_width": { "description": "Width in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "media_type": { - "description": "The media category, e.g. `\"video\"` or `\"audio\"`. Present on `media` type only. `null` otherwise.", + "description": "The media category, e.g. `\"video\"` or `\"audio\"`. Present on `media` type only; omitted otherwise.", "example": "application/json", "type": "string" }, "name": { "description": "Display name of the media item. Present on `media` type only. `null` otherwise.", "example": "Example Name", + "nullable": true, "type": "string" }, "object": { - "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`. `null` on other types.", + "description": "The full embedded object payload. For `task` type, contains the task record. For `action` type, contains the action definition. For `chart` type, contains the chart with its inline `spec`. Omitted on other types.", "example": {}, "type": "object" }, "title": { "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.", "example": "Example Title", + "nullable": true, "type": "string" }, "type": { @@ -82935,10 +91433,11 @@ "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "variants": { - "description": "Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only. `null` otherwise.", + "description": "Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only; omitted otherwise.", "example": [ { "content_type": "application/json", @@ -82989,6 +91488,7 @@ "content_type": { "description": "MIME type of this variant's file (e.g., `\"image/jpeg\"`, `\"video/mp4\"`). `null` if the file is not loaded.", "example": "application/json", + "nullable": true, "type": "string" }, "created_at": { @@ -83005,11 +91505,13 @@ "filename": { "description": "Original filename of the uploaded file for this variant. `null` if the file is not loaded.", "example": "string", + "nullable": true, "type": "string" }, "height": { "description": "Height of this variant in pixels. `null` if not recorded.", "example": 600, + "nullable": true, "type": "integer" }, "id": { @@ -83028,40 +91530,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -83076,6 +91586,7 @@ "url": { "description": "Signed download URL for this variant, resolved at request time. `null` if the file is unavailable.", "example": "https://example.com", + "nullable": true, "type": "string" }, "variant_key": { @@ -83086,6 +91597,7 @@ "width": { "description": "Width of this variant in pixels. `null` if not recorded.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -83099,11 +91611,13 @@ "version": { "description": "Version number of the attached artifact at the time of attachment. Present on `artifact` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "width": { "description": "Width in pixels of the media item. Present on `media` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" } }, @@ -83118,17 +91632,18 @@ "branched_thread": { "description": "ID of the thread that was branched from this message (`thr_...`). `null` if this message has not spawned a branch thread.", "example": "string", + "nullable": true, "type": "string" }, "content": { "description": "Text content of the message. `null` for messages that contain only attachments.", "example": "Hello, how can I help you today?", + "nullable": true, "type": "string" }, "created_at": { "description": "When the message was posted (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "has_replies": { @@ -83144,6 +91659,7 @@ "idempotency_key": { "description": "Client-supplied idempotency key used to deduplicate message sends. `null` if the sender did not provide one.", "example": "01234567-89ab-cdef-0123-456789abcdef", + "nullable": true, "type": "string" }, "is_deleted": { @@ -83154,6 +91670,7 @@ "legacy_agent": { "description": "Identifier of the legacy chat agent that sent this message, if applicable. `null` for messages sent by users or modern agent users.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -83166,6 +91683,7 @@ "org": { "description": "ID of the organization that owns this message (`org_...`).", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "reactions": { @@ -83217,6 +91735,7 @@ "rendering_mode": { "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.", "example": "reply", + "nullable": true, "type": "string" }, "replies": { @@ -83232,11 +91751,13 @@ "replies_after_cursor": { "description": "Opaque pagination cursor to fetch replies posted after the current page. Only present when inline replies are included in the response.", "example": "string", + "nullable": true, "type": "string" }, "replies_before_cursor": { "description": "Opaque pagination cursor to fetch replies posted before the current page. Only present when inline replies are included in the response.", "example": "string", + "nullable": true, "type": "string" }, "reply_count": { @@ -83379,9 +91900,10 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, + "nullable": true, "type": "object" }, "root_message_id": { @@ -83393,27 +91915,180 @@ "sandbox": { "description": "ID of the developer sandbox this message belongs to (`dsb_...`). `null` for non-sandbox messages.", "example": "string", + "nullable": true, "type": "string" }, "team": { "description": "ID of the team this message is scoped to (`tem_...`). `null` if the message is not team-scoped.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "thread": { - "description": "ID of the thread this message belongs to (`thr_...`). `null` for messages not yet associated with a thread.", + "description": "ID of the thread this message belongs to (`thr_...`).", "example": "string", "type": "string" }, "type": { "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.", "example": "note", + "nullable": true, "type": "string" }, "user": { "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.", - "example": "string", - "type": "string" + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "oneOf": [ + { + "type": "string" + }, + { + "description": "A platform user account. Represents a human or system actor that can own threads, belong to an organization, and interact with the API.", + "example": { + "alias": "jdoe", + "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "email": "user@example.com", + "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "is_system_user": true, + "metadata": { + "key": "value" + }, + "name": "Example Name", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "org_name": "Example Name", + "org_role": "member", + "org_slug": "example-slug", + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "sandbox_name": "Example Name" + }, + "properties": { + "alias": { + "description": "Short handle or alias for the user. `null` if not set.", + "example": "jdoe", + "nullable": true, + "type": "string" + }, + "app": { + "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.", + "example": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "app_name": { + "description": "Display name of the user's app. `null` when the app association was not preloaded by the caller.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "created_by_agent_user": { + "description": "Agent user that created this account (`usr_...`). `null` unless an agent created it.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_developer": { + "description": "Developer account that created this user (`dva_...`). `null` unless created via a developer token.", + "example": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_org": { + "description": "Org of the principal that created this user (`org_...`). `null` on legacy rows.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_team": { + "description": "Team that created this user (`tem_...`). `null` unless created as a team.", + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_user": { + "description": "User who created this account (`usr_...`). `null` on self-signup or legacy rows.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "email": { + "description": "Email address of the user.", + "example": "user@example.com", + "nullable": true, + "type": "string" + }, + "id": { + "description": "User ID (`usr_...`).", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "is_system_user": { + "description": "`true` if this account is an internal system user rather than a human. System users are created automatically by the platform.", + "example": true, + "type": "boolean" + }, + "metadata": { + "description": "Arbitrary key-value metadata attached to the user. Defaults to an empty object.", + "example": { + "key": "value" + }, + "type": "object" + }, + "name": { + "description": "Full display name of the user. `null` if the user has not set a name.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "org": { + "description": "ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "org_name": { + "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.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "org_role": { + "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.", + "example": "member", + "nullable": true, + "type": "string" + }, + "org_slug": { + "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.", + "example": "example-slug", + "nullable": true, + "type": "string" + }, + "sandbox": { + "description": "ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.", + "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "sandbox_name": { + "description": "Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.", + "example": "Example Name", + "nullable": true, + "type": "string" + } + }, + "required": [ + "id" + ], + "type": "object" + } + ] }, "visibility": { "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.", @@ -83514,6 +92189,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -83665,6 +92341,7 @@ "badges": { "description": "Aggregated badge counts for the team, keyed by category. `null` when badge data is not loaded.", "example": {}, + "nullable": true, "type": "object" }, "created_at": { @@ -83676,6 +92353,7 @@ "description": { "description": "Human-readable description of the team's purpose. `null` if not set.", "example": "An example description.", + "nullable": true, "type": "string" }, "id": { @@ -83686,6 +92364,7 @@ "membership_status": { "description": "The authenticated viewer's role on this team. One of `\"owner\"`, `\"admin\"`, or `\"member\"`. `null` if the viewer is not a member.", "example": "member", + "nullable": true, "type": "string" }, "metadata": { @@ -83703,16 +92382,19 @@ "org": { "description": "ID of the organization this team belongs to (`org_...`). `null` if the team is not org-scoped.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the developer sandbox this team is scoped to (`dsb_...`). `null` outside sandbox contexts.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "slug": { "description": "URL-safe slug for the team, derived from the team name. `null` if not set.", "example": "example-slug", + "nullable": true, "type": "string" }, "updated_at": { @@ -83882,7 +92564,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "participant": [ @@ -83893,6 +92575,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -83903,6 +92590,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -84108,7 +92796,7 @@ ], "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "title": "Example Title", - "ttl": 3600, + "ttl": "2026-08-15T12:00:00", "unread_count": 5, "updated_at": "2024-01-01T00:00:00Z", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", @@ -84118,17 +92806,18 @@ "agent_user": { "description": "ID of the agent that owns this thread (`agt_...`). `null` for user-owned or team-owned threads.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "created_at": { "description": "When the thread was created (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "creator": { "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.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "oneOf": [ { "type": "string" @@ -84139,6 +92828,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -84149,6 +92843,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" }, @@ -84156,21 +92851,55 @@ "alias": { "description": "Short handle or alias for the user. `null` if not set.", "example": "jdoe", + "nullable": true, "type": "string" }, "app": { "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.", "example": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "app_name": { "description": "Display name of the user's app. `null` when the app association was not preloaded by the caller.", "example": "Example Name", + "nullable": true, + "type": "string" + }, + "created_by_agent_user": { + "description": "Agent user that created this account (`usr_...`). `null` unless an agent created it.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_developer": { + "description": "Developer account that created this user (`dva_...`). `null` unless created via a developer token.", + "example": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_org": { + "description": "Org of the principal that created this user (`org_...`). `null` on legacy rows.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_team": { + "description": "Team that created this user (`tem_...`). `null` unless created as a team.", + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_user": { + "description": "User who created this account (`usr_...`). `null` on self-signup or legacy rows.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "email": { "description": "Email address of the user.", "example": "user@example.com", + "nullable": true, "type": "string" }, "id": { @@ -84193,31 +92922,43 @@ "name": { "description": "Full display name of the user. `null` if the user has not set a name.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "description": "ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_name": { "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.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_role": { "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.", "example": "member", + "nullable": true, + "type": "string" + }, + "org_slug": { + "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.", + "example": "example-slug", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "sandbox_name": { "description": "Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.", "example": "Example Name", + "nullable": true, "type": "string" } }, @@ -84231,6 +92972,7 @@ "description": { "description": "Optional description or purpose statement for the thread. `null` if not set.", "example": "An example description.", + "nullable": true, "type": "string" }, "id": { @@ -84261,27 +93003,31 @@ "key": { "description": "Application-defined stable key that uniquely identifies the thread within its scope. Useful for idempotent creation. `null` if not set.", "example": "string", + "nullable": true, "type": "string" }, "kind": { - "description": "Thread subtype: `\"standard\"` for ordinary threads, `\"slack_mirror\"` for the membership-strict mirror of a Slack channel, `\"slashwork_mirror\"` for the membership-strict mirror of a Slashwork group. Read-only — derived server-side at creation, never accepted from params.", + "description": "Thread subtype: `\"standard\"` for ordinary threads, `\"personal\"` for a user-and-owned-agents roster, `\"slack_mirror\"` for the membership-strict mirror of a Slack channel, or `\"slashwork_mirror\"` for the membership-strict mirror of a Slashwork group. `personal` is an explicit user-thread creation option; mirror kinds are server-derived.", "example": "string", + "nullable": true, "type": "string" }, "last_activity": { "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.", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", + "nullable": true, "type": "string" }, "last_message_preview": { "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.", "example": "Sounds good — I'll ship the fix tomorrow.", + "nullable": true, "type": "string" }, "last_message_sender": { "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.", "example": "Alice Chen", + "nullable": true, "type": "string" }, "metadata": { @@ -84289,6 +93035,7 @@ "example": { "key": "value" }, + "nullable": true, "type": "object" }, "muted": { @@ -84299,6 +93046,7 @@ "org": { "description": "ID of the organization this thread belongs to (`org_...`). `null` for threads outside an org context.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "parent_message": { @@ -84436,9 +93184,10 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, + "nullable": true, "properties": { "acl": { "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.", @@ -84470,6 +93219,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -84651,16 +93401,19 @@ "alias": { "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", "example": "alice", + "nullable": true, "type": "string" }, "id": { "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "nullable": true, "type": "string" }, "name": { "description": "Display name of the actor shown in the UI. `null` if no name is set.", "example": "Example Name", + "nullable": true, "type": "string" }, "profile_picture": { @@ -84674,40 +93427,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -84721,6 +93482,7 @@ "agent": { "description": "ID of the agent user that sent this message (`agi_...`). `null` for messages sent by human users.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "agent_mode": { @@ -84730,6 +93492,7 @@ "embedded" ], "example": "cli", + "nullable": true, "type": "string" }, "attachments": { @@ -84842,21 +93605,25 @@ "content_type": { "description": "MIME type of the attached file, e.g. `\"image/png\"` or `\"application/pdf\"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.", "example": "application/json", + "nullable": true, "type": "string" }, "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "filename": { "description": "Original filename of the attached file, e.g. `\"report.pdf\"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.", "example": "string", + "nullable": true, "type": "string" }, "height": { "description": "Height in pixels of the media item. Present on `media` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "id": { @@ -84867,6 +93634,7 @@ "image_height": { "description": "Height in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "image_source": { @@ -84880,40 +93648,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -84922,31 +93698,35 @@ "image_url": { "description": "URL of the preview image extracted from the scraped page. Present on `scraped_link` type only. `null` otherwise.", "example": "https://example.com", + "nullable": true, "type": "string" }, "image_width": { "description": "Width in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "media_type": { - "description": "The media category, e.g. `\"video\"` or `\"audio\"`. Present on `media` type only. `null` otherwise.", + "description": "The media category, e.g. `\"video\"` or `\"audio\"`. Present on `media` type only; omitted otherwise.", "example": "application/json", "type": "string" }, "name": { "description": "Display name of the media item. Present on `media` type only. `null` otherwise.", "example": "Example Name", + "nullable": true, "type": "string" }, "object": { - "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`. `null` on other types.", + "description": "The full embedded object payload. For `task` type, contains the task record. For `action` type, contains the action definition. For `chart` type, contains the chart with its inline `spec`. Omitted on other types.", "example": {}, "type": "object" }, "title": { "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.", "example": "Example Title", + "nullable": true, "type": "string" }, "type": { @@ -84957,10 +93737,11 @@ "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "variants": { - "description": "Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only. `null` otherwise.", + "description": "Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only; omitted otherwise.", "example": [ { "content_type": "application/json", @@ -85011,6 +93792,7 @@ "content_type": { "description": "MIME type of this variant's file (e.g., `\"image/jpeg\"`, `\"video/mp4\"`). `null` if the file is not loaded.", "example": "application/json", + "nullable": true, "type": "string" }, "created_at": { @@ -85027,11 +93809,13 @@ "filename": { "description": "Original filename of the uploaded file for this variant. `null` if the file is not loaded.", "example": "string", + "nullable": true, "type": "string" }, "height": { "description": "Height of this variant in pixels. `null` if not recorded.", "example": 600, + "nullable": true, "type": "integer" }, "id": { @@ -85050,40 +93834,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -85098,6 +93890,7 @@ "url": { "description": "Signed download URL for this variant, resolved at request time. `null` if the file is unavailable.", "example": "https://example.com", + "nullable": true, "type": "string" }, "variant_key": { @@ -85108,6 +93901,7 @@ "width": { "description": "Width of this variant in pixels. `null` if not recorded.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -85121,11 +93915,13 @@ "version": { "description": "Version number of the attached artifact at the time of attachment. Present on `artifact` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "width": { "description": "Width in pixels of the media item. Present on `media` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" } }, @@ -85140,17 +93936,18 @@ "branched_thread": { "description": "ID of the thread that was branched from this message (`thr_...`). `null` if this message has not spawned a branch thread.", "example": "string", + "nullable": true, "type": "string" }, "content": { "description": "Text content of the message. `null` for messages that contain only attachments.", "example": "Hello, how can I help you today?", + "nullable": true, "type": "string" }, "created_at": { "description": "When the message was posted (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "has_replies": { @@ -85166,6 +93963,7 @@ "idempotency_key": { "description": "Client-supplied idempotency key used to deduplicate message sends. `null` if the sender did not provide one.", "example": "01234567-89ab-cdef-0123-456789abcdef", + "nullable": true, "type": "string" }, "is_deleted": { @@ -85176,6 +93974,7 @@ "legacy_agent": { "description": "Identifier of the legacy chat agent that sent this message, if applicable. `null` for messages sent by users or modern agent users.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -85188,6 +93987,7 @@ "org": { "description": "ID of the organization that owns this message (`org_...`).", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "reactions": { @@ -85239,6 +94039,7 @@ "rendering_mode": { "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.", "example": "reply", + "nullable": true, "type": "string" }, "replies": { @@ -85254,11 +94055,13 @@ "replies_after_cursor": { "description": "Opaque pagination cursor to fetch replies posted after the current page. Only present when inline replies are included in the response.", "example": "string", + "nullable": true, "type": "string" }, "replies_before_cursor": { "description": "Opaque pagination cursor to fetch replies posted before the current page. Only present when inline replies are included in the response.", "example": "string", + "nullable": true, "type": "string" }, "reply_count": { @@ -85401,9 +94204,10 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, + "nullable": true, "type": "object" }, "root_message_id": { @@ -85415,27 +94219,180 @@ "sandbox": { "description": "ID of the developer sandbox this message belongs to (`dsb_...`). `null` for non-sandbox messages.", "example": "string", + "nullable": true, "type": "string" }, "team": { "description": "ID of the team this message is scoped to (`tem_...`). `null` if the message is not team-scoped.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "thread": { - "description": "ID of the thread this message belongs to (`thr_...`). `null` for messages not yet associated with a thread.", + "description": "ID of the thread this message belongs to (`thr_...`).", "example": "string", "type": "string" }, "type": { "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.", "example": "note", + "nullable": true, "type": "string" }, "user": { "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.", - "example": "string", - "type": "string" + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "oneOf": [ + { + "type": "string" + }, + { + "description": "A platform user account. Represents a human or system actor that can own threads, belong to an organization, and interact with the API.", + "example": { + "alias": "jdoe", + "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "email": "user@example.com", + "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "is_system_user": true, + "metadata": { + "key": "value" + }, + "name": "Example Name", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "org_name": "Example Name", + "org_role": "member", + "org_slug": "example-slug", + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "sandbox_name": "Example Name" + }, + "properties": { + "alias": { + "description": "Short handle or alias for the user. `null` if not set.", + "example": "jdoe", + "nullable": true, + "type": "string" + }, + "app": { + "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.", + "example": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "app_name": { + "description": "Display name of the user's app. `null` when the app association was not preloaded by the caller.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "created_by_agent_user": { + "description": "Agent user that created this account (`usr_...`). `null` unless an agent created it.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_developer": { + "description": "Developer account that created this user (`dva_...`). `null` unless created via a developer token.", + "example": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_org": { + "description": "Org of the principal that created this user (`org_...`). `null` on legacy rows.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_team": { + "description": "Team that created this user (`tem_...`). `null` unless created as a team.", + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_user": { + "description": "User who created this account (`usr_...`). `null` on self-signup or legacy rows.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "email": { + "description": "Email address of the user.", + "example": "user@example.com", + "nullable": true, + "type": "string" + }, + "id": { + "description": "User ID (`usr_...`).", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "is_system_user": { + "description": "`true` if this account is an internal system user rather than a human. System users are created automatically by the platform.", + "example": true, + "type": "boolean" + }, + "metadata": { + "description": "Arbitrary key-value metadata attached to the user. Defaults to an empty object.", + "example": { + "key": "value" + }, + "type": "object" + }, + "name": { + "description": "Full display name of the user. `null` if the user has not set a name.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "org": { + "description": "ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "org_name": { + "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.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "org_role": { + "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.", + "example": "member", + "nullable": true, + "type": "string" + }, + "org_slug": { + "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.", + "example": "example-slug", + "nullable": true, + "type": "string" + }, + "sandbox": { + "description": "ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.", + "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "sandbox_name": { + "description": "Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.", + "example": "Example Name", + "nullable": true, + "type": "string" + } + }, + "required": [ + "id" + ], + "type": "object" + } + ] }, "visibility": { "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.", @@ -85469,6 +94426,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -85479,6 +94441,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -85489,6 +94452,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -85499,6 +94467,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" }, @@ -85506,21 +94475,55 @@ "alias": { "description": "Short handle or alias for the user. `null` if not set.", "example": "jdoe", + "nullable": true, "type": "string" }, "app": { "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.", "example": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "app_name": { "description": "Display name of the user's app. `null` when the app association was not preloaded by the caller.", "example": "Example Name", + "nullable": true, + "type": "string" + }, + "created_by_agent_user": { + "description": "Agent user that created this account (`usr_...`). `null` unless an agent created it.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_developer": { + "description": "Developer account that created this user (`dva_...`). `null` unless created via a developer token.", + "example": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_org": { + "description": "Org of the principal that created this user (`org_...`). `null` on legacy rows.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_team": { + "description": "Team that created this user (`tem_...`). `null` unless created as a team.", + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_user": { + "description": "User who created this account (`usr_...`). `null` on self-signup or legacy rows.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "email": { "description": "Email address of the user.", "example": "user@example.com", + "nullable": true, "type": "string" }, "id": { @@ -85543,31 +94546,43 @@ "name": { "description": "Full display name of the user. `null` if the user has not set a name.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "description": "ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_name": { "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.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_role": { "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.", "example": "member", + "nullable": true, + "type": "string" + }, + "org_slug": { + "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.", + "example": "example-slug", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "sandbox_name": { "description": "Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.", "example": "Example Name", + "nullable": true, "type": "string" } }, @@ -85805,7 +94820,7 @@ ] }, "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", - "created_at": "2024-01-01T00:00:00Z", + "created_at": "string", "default_model": "claude-3-7-sonnet-latest", "description": "An example description.", "email": "user@example.com", @@ -85953,9 +94968,10 @@ }, "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "template_upgrade_available": true, - "updated_at": "2024-01-01T00:00:00Z", + "updated_at": "string", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" }, + "nullable": true, "properties": { "acl": { "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.", @@ -85987,6 +95003,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -86137,23 +95154,25 @@ }, "created_at": { "description": "When the agent was created (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "default_model": { "description": "Default LLM model identifier used by this agent when no model is specified at runtime (e.g. `\"claude-3-7-sonnet-latest\"`).", "example": "claude-3-7-sonnet-latest", + "nullable": true, "type": "string" }, "description": { "description": "Human-readable description of what the agent does. `null` if not set.", "example": "An example description.", + "nullable": true, "type": "string" }, "email": { "description": "Email address provisioned for this agent. `null` if email delivery is not configured.", "example": "user@example.com", + "nullable": true, "type": "string" }, "id": { @@ -86164,16 +95183,19 @@ "identity": { "description": "System-level identity prompt that shapes the agent's persona and behavior.", "example": "You are a helpful assistant that answers questions about ArchAstro products.", + "nullable": true, "type": "string" }, "last_applied_template_config": { "description": "ID of the AgentTemplate config (`cfg_...`) this agent was last provisioned or updated from. `null` for manually created agents.", "example": "cfg_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "lookup_key": { "description": "Stable, user-defined identifier for this agent within the application. Unique per app.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -86191,26 +95213,31 @@ "org": { "description": "ID of the organization this agent belongs to (`org_...`). `null` if the agent is not org-scoped.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_name": { "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.", "example": "Example Name", + "nullable": true, "type": "string" }, "originator": { "description": "Free-form label identifying the source or author that created this agent (e.g. a username or pipeline name).", "example": "deploy-pipeline", + "nullable": true, "type": "string" }, "phone_number": { "description": "Phone number provisioned for this agent. `null` if SMS is not configured.", "example": "+15555550123", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the sandbox environment this agent is scoped to (`dsb_...`). `null` in production deployments.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "source_solution": { @@ -86344,6 +95371,7 @@ "virtual_path": "string" } }, + "nullable": true, "properties": { "current_solution": { "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.", @@ -86418,13 +95446,13 @@ }, "created_at": { "description": "When the Solution config was first imported (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "events": { @@ -86440,6 +95468,7 @@ "image_url": { "description": "Absolute URL of the Solution's cover image — the bundled asset the body's `image:` field names. A stable, non-expiring capability URL (like `org_logo.url`), safe to hold in caches and OpenGraph tags; it 404s if the Solution stops declaring a cover. `null` when the Solution has no cover image, and always `null` for org-scoped rows — the permanent URL is minted for system-scope (catalog) Solutions only.", "example": "https://example.com", + "nullable": true, "type": "string" }, "kind": { @@ -86450,16 +95479,19 @@ "latest_solution": { "description": "When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "latest_version": { "description": "When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", "example": "1.0.0", + "nullable": true, "type": "string" }, "lookup_key": { "description": "The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -86472,11 +95504,13 @@ "name": { "description": "Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "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.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_logo": { @@ -86490,40 +95524,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -86532,11 +95574,13 @@ "org_name": { "description": "Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_slug": { "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.", "example": "example-slug", + "nullable": true, "type": "string" }, "owners": { @@ -86552,6 +95596,7 @@ "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "screenshot_urls": { @@ -86567,11 +95612,13 @@ "solution_id": { "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.", "example": "01234567-89ab-cdef-0123-456789abcdef", + "nullable": true, "type": "string" }, "solution_version": { "description": "Semver string declared in the Solution body (e.g. `\"1.2.0\"`). `null` when the body does not declare a version.", "example": "1.2.0", + "nullable": true, "type": "string" }, "tag_keys": { @@ -86587,6 +95634,7 @@ "template_kind": { "description": "Wrapped template kind — `\"AgentTemplate\"`, `\"AutomationTemplate\"`, `\"AgentRoutineTemplate\"`, `\"AgentToolTemplate\"`, `\"AgentComputerTemplate\"`, or `\"SolutionTemplateRef\"` for ref-mode bundles.", "example": "AgentTemplate", + "nullable": true, "type": "string" }, "templates": { @@ -86619,6 +95667,7 @@ "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "details": { @@ -86626,6 +95675,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -86650,12 +95700,13 @@ }, "properties": { "automation_type": { - "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`).", + "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", "example": "string", + "nullable": true, "type": "string" }, "invoke_contract": { - "description": "Schema-driven payload and participant inputs for an invoked automation. Used by installation clients to collect locked prefills before provisioning.", + "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.", "example": { "input_schema": {}, "participants": [ @@ -86671,10 +95722,12 @@ "payload": {} } }, + "nullable": true, "properties": { "input_schema": { "description": "JSON Schema validated against the whole invoke payload, from the automation's `input_schema_config`. `null` when none is configured.", "example": {}, + "nullable": true, "type": "object" }, "participants": { @@ -86695,10 +95748,12 @@ "required": true, "type": "agent_user" }, + "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", "example": "An example description.", + "nullable": true, "type": "string" }, "name": { @@ -86724,6 +95779,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -86772,11 +95828,13 @@ "display_name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "id": { "description": "Template config ID (`cfg_...`). `null` for inline-only templates.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "kind": { @@ -86787,21 +95845,25 @@ "lookup_key": { "description": "Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", "example": "string", + "nullable": true, "type": "string" }, "name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "virtual_path": { "description": "Stable virtual path assigned to the template config. `null` when no virtual path was set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -86814,8 +95876,7 @@ }, "updated_at": { "description": "When the Solution config was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "upgrade_available": { @@ -86826,6 +95887,7 @@ "virtual_path": { "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.", "example": "string", + "nullable": true, "type": "string" } }, @@ -86911,13 +95973,13 @@ }, "created_at": { "description": "When the Solution config was first imported (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "events": { @@ -86933,6 +95995,7 @@ "image_url": { "description": "Absolute URL of the Solution's cover image — the bundled asset the body's `image:` field names. A stable, non-expiring capability URL (like `org_logo.url`), safe to hold in caches and OpenGraph tags; it 404s if the Solution stops declaring a cover. `null` when the Solution has no cover image, and always `null` for org-scoped rows — the permanent URL is minted for system-scope (catalog) Solutions only.", "example": "https://example.com", + "nullable": true, "type": "string" }, "kind": { @@ -86943,16 +96006,19 @@ "latest_solution": { "description": "When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "latest_version": { "description": "When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", "example": "1.0.0", + "nullable": true, "type": "string" }, "lookup_key": { "description": "The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -86965,11 +96031,13 @@ "name": { "description": "Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "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.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_logo": { @@ -86983,40 +96051,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -87025,11 +96101,13 @@ "org_name": { "description": "Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_slug": { "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.", "example": "example-slug", + "nullable": true, "type": "string" }, "owners": { @@ -87045,6 +96123,7 @@ "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "screenshot_urls": { @@ -87060,11 +96139,13 @@ "solution_id": { "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.", "example": "01234567-89ab-cdef-0123-456789abcdef", + "nullable": true, "type": "string" }, "solution_version": { "description": "Semver string declared in the Solution body (e.g. `\"1.2.0\"`). `null` when the body does not declare a version.", "example": "1.2.0", + "nullable": true, "type": "string" }, "tag_keys": { @@ -87080,6 +96161,7 @@ "template_kind": { "description": "Wrapped template kind — `\"AgentTemplate\"`, `\"AutomationTemplate\"`, `\"AgentRoutineTemplate\"`, `\"AgentToolTemplate\"`, `\"AgentComputerTemplate\"`, or `\"SolutionTemplateRef\"` for ref-mode bundles.", "example": "AgentTemplate", + "nullable": true, "type": "string" }, "templates": { @@ -87112,6 +96194,7 @@ "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "details": { @@ -87119,6 +96202,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -87143,12 +96227,13 @@ }, "properties": { "automation_type": { - "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`).", + "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", "example": "string", + "nullable": true, "type": "string" }, "invoke_contract": { - "description": "Schema-driven payload and participant inputs for an invoked automation. Used by installation clients to collect locked prefills before provisioning.", + "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.", "example": { "input_schema": {}, "participants": [ @@ -87164,10 +96249,12 @@ "payload": {} } }, + "nullable": true, "properties": { "input_schema": { "description": "JSON Schema validated against the whole invoke payload, from the automation's `input_schema_config`. `null` when none is configured.", "example": {}, + "nullable": true, "type": "object" }, "participants": { @@ -87188,10 +96275,12 @@ "required": true, "type": "agent_user" }, + "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", "example": "An example description.", + "nullable": true, "type": "string" }, "name": { @@ -87217,6 +96306,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -87265,11 +96355,13 @@ "display_name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "id": { "description": "Template config ID (`cfg_...`). `null` for inline-only templates.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "kind": { @@ -87280,21 +96372,25 @@ "lookup_key": { "description": "Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", "example": "string", + "nullable": true, "type": "string" }, "name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "virtual_path": { "description": "Stable virtual path assigned to the template config. `null` when no virtual path was set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -87307,8 +96403,7 @@ }, "updated_at": { "description": "When the Solution config was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "upgrade_available": { @@ -87319,6 +96414,7 @@ "virtual_path": { "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.", "example": "string", + "nullable": true, "type": "string" } }, @@ -87354,11 +96450,13 @@ "description": { "description": "Description of the template from the config body. `null` if the current version has no `description` field.", "example": "An example description.", + "nullable": true, "type": "string" }, "display_name": { "description": "Human-readable display name from the config body. `null` if the current version has no `display_name` field.", "example": "Example Name", + "nullable": true, "type": "string" }, "id": { @@ -87374,11 +96472,13 @@ "lookup_key": { "description": "Stable lookup key assigned to this template config. `null` if no lookup key is set.", "example": "string", + "nullable": true, "type": "string" }, "name": { "description": "Template name as stored in the config body. `null` if the current version has no `name` field.", "example": "Example Name", + "nullable": true, "type": "string" }, "updated_at": { @@ -87390,6 +96490,7 @@ "virtual_path": { "description": "Virtual filesystem path for this template config. `null` if not set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -87409,22 +96510,24 @@ "team": { "description": "ID of the team that owns this agent (`tem_...`). `null` if the agent is not team-scoped.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "template_upgrade_available": { "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`).", "example": true, + "nullable": true, "type": "boolean" }, "updated_at": { "description": "When the agent was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "user": { "description": "ID of the user that owns this agent (`usr_...`). `null` if the agent is not user-scoped.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" } }, @@ -87433,16 +96536,19 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "role": { "description": "The authenticated user's membership role in this thread, e.g. `\"owner\"`, `\"member\"`, or `\"viewer\"`. `null` if the user is not a member.", "example": "member", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the developer sandbox this thread is scoped to (`dsb_...`). `null` for production threads.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "settings": { @@ -87452,8 +96558,9 @@ }, "properties": { "agent_enabled": { - "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.", + "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.", "example": true, + "nullable": true, "type": "boolean" } }, @@ -87462,6 +96569,7 @@ "slug": { "description": "URL-safe slug for the thread, used in human-readable permalinks. `null` if not assigned.", "example": "example-slug", + "nullable": true, "type": "string" }, "sub_threads": { @@ -87470,8 +96578,10 @@ {} ], "items": { + "nullable": true, "type": "object" }, + "nullable": true, "type": "array" }, "tags": { @@ -87488,32 +96598,36 @@ "team": { "description": "ID of the team that owns this thread (`team_...`). `null` for user-owned or agent-owned threads.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "title": { "description": "Human-readable name of the thread. `null` if no title has been set.", "example": "Example Title", + "nullable": true, "type": "string" }, "ttl": { - "description": "Time-to-live in seconds after which the thread may be automatically cleaned up. `null` if the thread does not expire.", - "example": 3600, - "type": "integer" + "description": "Offset-free expiry timestamp after which the thread may be automatically cleaned up. `null` if the thread does not expire.", + "example": "2026-08-15T12:00:00", + "nullable": true, + "type": "string" }, "unread_count": { "description": "Number of messages in this thread that the authenticated user has not yet read. Present only when read-state enrichment is requested.", "example": 5, + "nullable": true, "type": "integer" }, "updated_at": { "description": "When the thread was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "user": { "description": "ID of the user who owns this thread (`usr_...`). `null` for team-owned or agent-owned threads.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "visibility": { @@ -87619,6 +96733,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -87770,6 +96885,7 @@ "badges": { "description": "Aggregated badge counts for the team, keyed by category. `null` when badge data is not loaded.", "example": {}, + "nullable": true, "type": "object" }, "created_at": { @@ -87781,6 +96897,7 @@ "description": { "description": "Human-readable description of the team's purpose. `null` if not set.", "example": "An example description.", + "nullable": true, "type": "string" }, "id": { @@ -87791,6 +96908,7 @@ "membership_status": { "description": "The authenticated viewer's role on this team. One of `\"owner\"`, `\"admin\"`, or `\"member\"`. `null` if the viewer is not a member.", "example": "member", + "nullable": true, "type": "string" }, "metadata": { @@ -87808,16 +96926,19 @@ "org": { "description": "ID of the organization this team belongs to (`org_...`). `null` if the team is not org-scoped.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the developer sandbox this team is scoped to (`dsb_...`). `null` outside sandbox contexts.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "slug": { "description": "URL-safe slug for the team, derived from the team name. `null` if not set.", "example": "example-slug", + "nullable": true, "type": "string" }, "updated_at": { @@ -87987,7 +97108,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "participant": [ @@ -87998,6 +97119,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -88008,6 +97134,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -88213,7 +97340,7 @@ ], "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "title": "Example Title", - "ttl": 3600, + "ttl": "2026-08-15T12:00:00", "unread_count": 5, "updated_at": "2024-01-01T00:00:00Z", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", @@ -88223,17 +97350,18 @@ "agent_user": { "description": "ID of the agent that owns this thread (`agt_...`). `null` for user-owned or team-owned threads.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "created_at": { "description": "When the thread was created (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "creator": { "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.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "oneOf": [ { "type": "string" @@ -88244,6 +97372,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -88254,6 +97387,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" }, @@ -88261,21 +97395,55 @@ "alias": { "description": "Short handle or alias for the user. `null` if not set.", "example": "jdoe", + "nullable": true, "type": "string" }, "app": { "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.", "example": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "app_name": { "description": "Display name of the user's app. `null` when the app association was not preloaded by the caller.", "example": "Example Name", + "nullable": true, + "type": "string" + }, + "created_by_agent_user": { + "description": "Agent user that created this account (`usr_...`). `null` unless an agent created it.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_developer": { + "description": "Developer account that created this user (`dva_...`). `null` unless created via a developer token.", + "example": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_org": { + "description": "Org of the principal that created this user (`org_...`). `null` on legacy rows.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_team": { + "description": "Team that created this user (`tem_...`). `null` unless created as a team.", + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_user": { + "description": "User who created this account (`usr_...`). `null` on self-signup or legacy rows.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "email": { "description": "Email address of the user.", "example": "user@example.com", + "nullable": true, "type": "string" }, "id": { @@ -88298,31 +97466,43 @@ "name": { "description": "Full display name of the user. `null` if the user has not set a name.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "description": "ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_name": { "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.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_role": { "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.", "example": "member", + "nullable": true, + "type": "string" + }, + "org_slug": { + "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.", + "example": "example-slug", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "sandbox_name": { "description": "Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.", "example": "Example Name", + "nullable": true, "type": "string" } }, @@ -88336,6 +97516,7 @@ "description": { "description": "Optional description or purpose statement for the thread. `null` if not set.", "example": "An example description.", + "nullable": true, "type": "string" }, "id": { @@ -88366,27 +97547,31 @@ "key": { "description": "Application-defined stable key that uniquely identifies the thread within its scope. Useful for idempotent creation. `null` if not set.", "example": "string", + "nullable": true, "type": "string" }, "kind": { - "description": "Thread subtype: `\"standard\"` for ordinary threads, `\"slack_mirror\"` for the membership-strict mirror of a Slack channel, `\"slashwork_mirror\"` for the membership-strict mirror of a Slashwork group. Read-only — derived server-side at creation, never accepted from params.", + "description": "Thread subtype: `\"standard\"` for ordinary threads, `\"personal\"` for a user-and-owned-agents roster, `\"slack_mirror\"` for the membership-strict mirror of a Slack channel, or `\"slashwork_mirror\"` for the membership-strict mirror of a Slashwork group. `personal` is an explicit user-thread creation option; mirror kinds are server-derived.", "example": "string", + "nullable": true, "type": "string" }, "last_activity": { "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.", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", + "nullable": true, "type": "string" }, "last_message_preview": { "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.", "example": "Sounds good — I'll ship the fix tomorrow.", + "nullable": true, "type": "string" }, "last_message_sender": { "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.", "example": "Alice Chen", + "nullable": true, "type": "string" }, "metadata": { @@ -88394,6 +97579,7 @@ "example": { "key": "value" }, + "nullable": true, "type": "object" }, "muted": { @@ -88404,6 +97590,7 @@ "org": { "description": "ID of the organization this thread belongs to (`org_...`). `null` for threads outside an org context.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "parent_message": { @@ -88541,9 +97728,10 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, + "nullable": true, "properties": { "acl": { "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.", @@ -88575,6 +97763,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -88756,16 +97945,19 @@ "alias": { "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", "example": "alice", + "nullable": true, "type": "string" }, "id": { "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "nullable": true, "type": "string" }, "name": { "description": "Display name of the actor shown in the UI. `null` if no name is set.", "example": "Example Name", + "nullable": true, "type": "string" }, "profile_picture": { @@ -88779,40 +97971,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -88826,6 +98026,7 @@ "agent": { "description": "ID of the agent user that sent this message (`agi_...`). `null` for messages sent by human users.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "agent_mode": { @@ -88835,6 +98036,7 @@ "embedded" ], "example": "cli", + "nullable": true, "type": "string" }, "attachments": { @@ -88947,21 +98149,25 @@ "content_type": { "description": "MIME type of the attached file, e.g. `\"image/png\"` or `\"application/pdf\"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.", "example": "application/json", + "nullable": true, "type": "string" }, "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "filename": { "description": "Original filename of the attached file, e.g. `\"report.pdf\"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.", "example": "string", + "nullable": true, "type": "string" }, "height": { "description": "Height in pixels of the media item. Present on `media` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "id": { @@ -88972,6 +98178,7 @@ "image_height": { "description": "Height in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "image_source": { @@ -88985,40 +98192,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -89027,31 +98242,35 @@ "image_url": { "description": "URL of the preview image extracted from the scraped page. Present on `scraped_link` type only. `null` otherwise.", "example": "https://example.com", + "nullable": true, "type": "string" }, "image_width": { "description": "Width in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "media_type": { - "description": "The media category, e.g. `\"video\"` or `\"audio\"`. Present on `media` type only. `null` otherwise.", + "description": "The media category, e.g. `\"video\"` or `\"audio\"`. Present on `media` type only; omitted otherwise.", "example": "application/json", "type": "string" }, "name": { "description": "Display name of the media item. Present on `media` type only. `null` otherwise.", "example": "Example Name", + "nullable": true, "type": "string" }, "object": { - "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`. `null` on other types.", + "description": "The full embedded object payload. For `task` type, contains the task record. For `action` type, contains the action definition. For `chart` type, contains the chart with its inline `spec`. Omitted on other types.", "example": {}, "type": "object" }, "title": { "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.", "example": "Example Title", + "nullable": true, "type": "string" }, "type": { @@ -89062,10 +98281,11 @@ "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "variants": { - "description": "Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only. `null` otherwise.", + "description": "Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only; omitted otherwise.", "example": [ { "content_type": "application/json", @@ -89116,6 +98336,7 @@ "content_type": { "description": "MIME type of this variant's file (e.g., `\"image/jpeg\"`, `\"video/mp4\"`). `null` if the file is not loaded.", "example": "application/json", + "nullable": true, "type": "string" }, "created_at": { @@ -89132,11 +98353,13 @@ "filename": { "description": "Original filename of the uploaded file for this variant. `null` if the file is not loaded.", "example": "string", + "nullable": true, "type": "string" }, "height": { "description": "Height of this variant in pixels. `null` if not recorded.", "example": 600, + "nullable": true, "type": "integer" }, "id": { @@ -89155,40 +98378,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -89203,6 +98434,7 @@ "url": { "description": "Signed download URL for this variant, resolved at request time. `null` if the file is unavailable.", "example": "https://example.com", + "nullable": true, "type": "string" }, "variant_key": { @@ -89213,6 +98445,7 @@ "width": { "description": "Width of this variant in pixels. `null` if not recorded.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -89226,11 +98459,13 @@ "version": { "description": "Version number of the attached artifact at the time of attachment. Present on `artifact` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "width": { "description": "Width in pixels of the media item. Present on `media` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" } }, @@ -89245,17 +98480,18 @@ "branched_thread": { "description": "ID of the thread that was branched from this message (`thr_...`). `null` if this message has not spawned a branch thread.", "example": "string", + "nullable": true, "type": "string" }, "content": { "description": "Text content of the message. `null` for messages that contain only attachments.", "example": "Hello, how can I help you today?", + "nullable": true, "type": "string" }, "created_at": { "description": "When the message was posted (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "has_replies": { @@ -89271,6 +98507,7 @@ "idempotency_key": { "description": "Client-supplied idempotency key used to deduplicate message sends. `null` if the sender did not provide one.", "example": "01234567-89ab-cdef-0123-456789abcdef", + "nullable": true, "type": "string" }, "is_deleted": { @@ -89281,6 +98518,7 @@ "legacy_agent": { "description": "Identifier of the legacy chat agent that sent this message, if applicable. `null` for messages sent by users or modern agent users.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -89293,6 +98531,7 @@ "org": { "description": "ID of the organization that owns this message (`org_...`).", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "reactions": { @@ -89344,6 +98583,7 @@ "rendering_mode": { "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.", "example": "reply", + "nullable": true, "type": "string" }, "replies": { @@ -89359,11 +98599,13 @@ "replies_after_cursor": { "description": "Opaque pagination cursor to fetch replies posted after the current page. Only present when inline replies are included in the response.", "example": "string", + "nullable": true, "type": "string" }, "replies_before_cursor": { "description": "Opaque pagination cursor to fetch replies posted before the current page. Only present when inline replies are included in the response.", "example": "string", + "nullable": true, "type": "string" }, "reply_count": { @@ -89506,9 +98748,10 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, + "nullable": true, "type": "object" }, "root_message_id": { @@ -89520,27 +98763,180 @@ "sandbox": { "description": "ID of the developer sandbox this message belongs to (`dsb_...`). `null` for non-sandbox messages.", "example": "string", + "nullable": true, "type": "string" }, "team": { "description": "ID of the team this message is scoped to (`tem_...`). `null` if the message is not team-scoped.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "thread": { - "description": "ID of the thread this message belongs to (`thr_...`). `null` for messages not yet associated with a thread.", + "description": "ID of the thread this message belongs to (`thr_...`).", "example": "string", "type": "string" }, "type": { "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.", "example": "note", + "nullable": true, "type": "string" }, "user": { "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.", - "example": "string", - "type": "string" + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "oneOf": [ + { + "type": "string" + }, + { + "description": "A platform user account. Represents a human or system actor that can own threads, belong to an organization, and interact with the API.", + "example": { + "alias": "jdoe", + "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "email": "user@example.com", + "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "is_system_user": true, + "metadata": { + "key": "value" + }, + "name": "Example Name", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "org_name": "Example Name", + "org_role": "member", + "org_slug": "example-slug", + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "sandbox_name": "Example Name" + }, + "properties": { + "alias": { + "description": "Short handle or alias for the user. `null` if not set.", + "example": "jdoe", + "nullable": true, + "type": "string" + }, + "app": { + "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.", + "example": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "app_name": { + "description": "Display name of the user's app. `null` when the app association was not preloaded by the caller.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "created_by_agent_user": { + "description": "Agent user that created this account (`usr_...`). `null` unless an agent created it.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_developer": { + "description": "Developer account that created this user (`dva_...`). `null` unless created via a developer token.", + "example": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_org": { + "description": "Org of the principal that created this user (`org_...`). `null` on legacy rows.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_team": { + "description": "Team that created this user (`tem_...`). `null` unless created as a team.", + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_user": { + "description": "User who created this account (`usr_...`). `null` on self-signup or legacy rows.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "email": { + "description": "Email address of the user.", + "example": "user@example.com", + "nullable": true, + "type": "string" + }, + "id": { + "description": "User ID (`usr_...`).", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "is_system_user": { + "description": "`true` if this account is an internal system user rather than a human. System users are created automatically by the platform.", + "example": true, + "type": "boolean" + }, + "metadata": { + "description": "Arbitrary key-value metadata attached to the user. Defaults to an empty object.", + "example": { + "key": "value" + }, + "type": "object" + }, + "name": { + "description": "Full display name of the user. `null` if the user has not set a name.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "org": { + "description": "ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "org_name": { + "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.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "org_role": { + "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.", + "example": "member", + "nullable": true, + "type": "string" + }, + "org_slug": { + "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.", + "example": "example-slug", + "nullable": true, + "type": "string" + }, + "sandbox": { + "description": "ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.", + "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "sandbox_name": { + "description": "Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.", + "example": "Example Name", + "nullable": true, + "type": "string" + } + }, + "required": [ + "id" + ], + "type": "object" + } + ] }, "visibility": { "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.", @@ -89574,6 +98970,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -89584,6 +98985,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -89594,6 +98996,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -89604,6 +99011,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" }, @@ -89611,21 +99019,55 @@ "alias": { "description": "Short handle or alias for the user. `null` if not set.", "example": "jdoe", + "nullable": true, "type": "string" }, "app": { "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.", "example": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "app_name": { "description": "Display name of the user's app. `null` when the app association was not preloaded by the caller.", "example": "Example Name", + "nullable": true, + "type": "string" + }, + "created_by_agent_user": { + "description": "Agent user that created this account (`usr_...`). `null` unless an agent created it.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_developer": { + "description": "Developer account that created this user (`dva_...`). `null` unless created via a developer token.", + "example": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_org": { + "description": "Org of the principal that created this user (`org_...`). `null` on legacy rows.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_team": { + "description": "Team that created this user (`tem_...`). `null` unless created as a team.", + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_user": { + "description": "User who created this account (`usr_...`). `null` on self-signup or legacy rows.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "email": { "description": "Email address of the user.", "example": "user@example.com", + "nullable": true, "type": "string" }, "id": { @@ -89648,31 +99090,43 @@ "name": { "description": "Full display name of the user. `null` if the user has not set a name.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "description": "ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_name": { "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.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_role": { "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.", "example": "member", + "nullable": true, + "type": "string" + }, + "org_slug": { + "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.", + "example": "example-slug", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "sandbox_name": { "description": "Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.", "example": "Example Name", + "nullable": true, "type": "string" } }, @@ -89910,7 +99364,7 @@ ] }, "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", - "created_at": "2024-01-01T00:00:00Z", + "created_at": "string", "default_model": "claude-3-7-sonnet-latest", "description": "An example description.", "email": "user@example.com", @@ -90058,9 +99512,10 @@ }, "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "template_upgrade_available": true, - "updated_at": "2024-01-01T00:00:00Z", + "updated_at": "string", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" }, + "nullable": true, "properties": { "acl": { "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.", @@ -90092,6 +99547,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -90242,23 +99698,25 @@ }, "created_at": { "description": "When the agent was created (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "default_model": { "description": "Default LLM model identifier used by this agent when no model is specified at runtime (e.g. `\"claude-3-7-sonnet-latest\"`).", "example": "claude-3-7-sonnet-latest", + "nullable": true, "type": "string" }, "description": { "description": "Human-readable description of what the agent does. `null` if not set.", "example": "An example description.", + "nullable": true, "type": "string" }, "email": { "description": "Email address provisioned for this agent. `null` if email delivery is not configured.", "example": "user@example.com", + "nullable": true, "type": "string" }, "id": { @@ -90269,16 +99727,19 @@ "identity": { "description": "System-level identity prompt that shapes the agent's persona and behavior.", "example": "You are a helpful assistant that answers questions about ArchAstro products.", + "nullable": true, "type": "string" }, "last_applied_template_config": { "description": "ID of the AgentTemplate config (`cfg_...`) this agent was last provisioned or updated from. `null` for manually created agents.", "example": "cfg_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "lookup_key": { "description": "Stable, user-defined identifier for this agent within the application. Unique per app.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -90296,26 +99757,31 @@ "org": { "description": "ID of the organization this agent belongs to (`org_...`). `null` if the agent is not org-scoped.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_name": { "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.", "example": "Example Name", + "nullable": true, "type": "string" }, "originator": { "description": "Free-form label identifying the source or author that created this agent (e.g. a username or pipeline name).", "example": "deploy-pipeline", + "nullable": true, "type": "string" }, "phone_number": { "description": "Phone number provisioned for this agent. `null` if SMS is not configured.", "example": "+15555550123", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the sandbox environment this agent is scoped to (`dsb_...`). `null` in production deployments.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "source_solution": { @@ -90449,6 +99915,7 @@ "virtual_path": "string" } }, + "nullable": true, "properties": { "current_solution": { "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.", @@ -90523,13 +99990,13 @@ }, "created_at": { "description": "When the Solution config was first imported (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "events": { @@ -90545,6 +100012,7 @@ "image_url": { "description": "Absolute URL of the Solution's cover image — the bundled asset the body's `image:` field names. A stable, non-expiring capability URL (like `org_logo.url`), safe to hold in caches and OpenGraph tags; it 404s if the Solution stops declaring a cover. `null` when the Solution has no cover image, and always `null` for org-scoped rows — the permanent URL is minted for system-scope (catalog) Solutions only.", "example": "https://example.com", + "nullable": true, "type": "string" }, "kind": { @@ -90555,16 +100023,19 @@ "latest_solution": { "description": "When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "latest_version": { "description": "When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", "example": "1.0.0", + "nullable": true, "type": "string" }, "lookup_key": { "description": "The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -90577,11 +100048,13 @@ "name": { "description": "Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "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.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_logo": { @@ -90595,40 +100068,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -90637,11 +100118,13 @@ "org_name": { "description": "Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_slug": { "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.", "example": "example-slug", + "nullable": true, "type": "string" }, "owners": { @@ -90657,6 +100140,7 @@ "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "screenshot_urls": { @@ -90672,11 +100156,13 @@ "solution_id": { "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.", "example": "01234567-89ab-cdef-0123-456789abcdef", + "nullable": true, "type": "string" }, "solution_version": { "description": "Semver string declared in the Solution body (e.g. `\"1.2.0\"`). `null` when the body does not declare a version.", "example": "1.2.0", + "nullable": true, "type": "string" }, "tag_keys": { @@ -90692,6 +100178,7 @@ "template_kind": { "description": "Wrapped template kind — `\"AgentTemplate\"`, `\"AutomationTemplate\"`, `\"AgentRoutineTemplate\"`, `\"AgentToolTemplate\"`, `\"AgentComputerTemplate\"`, or `\"SolutionTemplateRef\"` for ref-mode bundles.", "example": "AgentTemplate", + "nullable": true, "type": "string" }, "templates": { @@ -90724,6 +100211,7 @@ "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "details": { @@ -90731,6 +100219,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -90755,12 +100244,13 @@ }, "properties": { "automation_type": { - "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`).", + "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", "example": "string", + "nullable": true, "type": "string" }, "invoke_contract": { - "description": "Schema-driven payload and participant inputs for an invoked automation. Used by installation clients to collect locked prefills before provisioning.", + "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.", "example": { "input_schema": {}, "participants": [ @@ -90776,10 +100266,12 @@ "payload": {} } }, + "nullable": true, "properties": { "input_schema": { "description": "JSON Schema validated against the whole invoke payload, from the automation's `input_schema_config`. `null` when none is configured.", "example": {}, + "nullable": true, "type": "object" }, "participants": { @@ -90800,10 +100292,12 @@ "required": true, "type": "agent_user" }, + "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", "example": "An example description.", + "nullable": true, "type": "string" }, "name": { @@ -90829,6 +100323,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -90877,11 +100372,13 @@ "display_name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "id": { "description": "Template config ID (`cfg_...`). `null` for inline-only templates.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "kind": { @@ -90892,21 +100389,25 @@ "lookup_key": { "description": "Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", "example": "string", + "nullable": true, "type": "string" }, "name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "virtual_path": { "description": "Stable virtual path assigned to the template config. `null` when no virtual path was set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -90919,8 +100420,7 @@ }, "updated_at": { "description": "When the Solution config was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "upgrade_available": { @@ -90931,6 +100431,7 @@ "virtual_path": { "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.", "example": "string", + "nullable": true, "type": "string" } }, @@ -91016,13 +100517,13 @@ }, "created_at": { "description": "When the Solution config was first imported (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "events": { @@ -91038,6 +100539,7 @@ "image_url": { "description": "Absolute URL of the Solution's cover image — the bundled asset the body's `image:` field names. A stable, non-expiring capability URL (like `org_logo.url`), safe to hold in caches and OpenGraph tags; it 404s if the Solution stops declaring a cover. `null` when the Solution has no cover image, and always `null` for org-scoped rows — the permanent URL is minted for system-scope (catalog) Solutions only.", "example": "https://example.com", + "nullable": true, "type": "string" }, "kind": { @@ -91048,16 +100550,19 @@ "latest_solution": { "description": "When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "latest_version": { "description": "When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", "example": "1.0.0", + "nullable": true, "type": "string" }, "lookup_key": { "description": "The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -91070,11 +100575,13 @@ "name": { "description": "Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "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.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_logo": { @@ -91088,40 +100595,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -91130,11 +100645,13 @@ "org_name": { "description": "Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_slug": { "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.", "example": "example-slug", + "nullable": true, "type": "string" }, "owners": { @@ -91150,6 +100667,7 @@ "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "screenshot_urls": { @@ -91165,11 +100683,13 @@ "solution_id": { "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.", "example": "01234567-89ab-cdef-0123-456789abcdef", + "nullable": true, "type": "string" }, "solution_version": { "description": "Semver string declared in the Solution body (e.g. `\"1.2.0\"`). `null` when the body does not declare a version.", "example": "1.2.0", + "nullable": true, "type": "string" }, "tag_keys": { @@ -91185,6 +100705,7 @@ "template_kind": { "description": "Wrapped template kind — `\"AgentTemplate\"`, `\"AutomationTemplate\"`, `\"AgentRoutineTemplate\"`, `\"AgentToolTemplate\"`, `\"AgentComputerTemplate\"`, or `\"SolutionTemplateRef\"` for ref-mode bundles.", "example": "AgentTemplate", + "nullable": true, "type": "string" }, "templates": { @@ -91217,6 +100738,7 @@ "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "details": { @@ -91224,6 +100746,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -91248,12 +100771,13 @@ }, "properties": { "automation_type": { - "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`).", + "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", "example": "string", + "nullable": true, "type": "string" }, "invoke_contract": { - "description": "Schema-driven payload and participant inputs for an invoked automation. Used by installation clients to collect locked prefills before provisioning.", + "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.", "example": { "input_schema": {}, "participants": [ @@ -91269,10 +100793,12 @@ "payload": {} } }, + "nullable": true, "properties": { "input_schema": { "description": "JSON Schema validated against the whole invoke payload, from the automation's `input_schema_config`. `null` when none is configured.", "example": {}, + "nullable": true, "type": "object" }, "participants": { @@ -91293,10 +100819,12 @@ "required": true, "type": "agent_user" }, + "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", "example": "An example description.", + "nullable": true, "type": "string" }, "name": { @@ -91322,6 +100850,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -91370,11 +100899,13 @@ "display_name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "id": { "description": "Template config ID (`cfg_...`). `null` for inline-only templates.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "kind": { @@ -91385,21 +100916,25 @@ "lookup_key": { "description": "Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", "example": "string", + "nullable": true, "type": "string" }, "name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "virtual_path": { "description": "Stable virtual path assigned to the template config. `null` when no virtual path was set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -91412,8 +100947,7 @@ }, "updated_at": { "description": "When the Solution config was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "upgrade_available": { @@ -91424,6 +100958,7 @@ "virtual_path": { "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.", "example": "string", + "nullable": true, "type": "string" } }, @@ -91459,11 +100994,13 @@ "description": { "description": "Description of the template from the config body. `null` if the current version has no `description` field.", "example": "An example description.", + "nullable": true, "type": "string" }, "display_name": { "description": "Human-readable display name from the config body. `null` if the current version has no `display_name` field.", "example": "Example Name", + "nullable": true, "type": "string" }, "id": { @@ -91479,11 +101016,13 @@ "lookup_key": { "description": "Stable lookup key assigned to this template config. `null` if no lookup key is set.", "example": "string", + "nullable": true, "type": "string" }, "name": { "description": "Template name as stored in the config body. `null` if the current version has no `name` field.", "example": "Example Name", + "nullable": true, "type": "string" }, "updated_at": { @@ -91495,6 +101034,7 @@ "virtual_path": { "description": "Virtual filesystem path for this template config. `null` if not set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -91514,22 +101054,24 @@ "team": { "description": "ID of the team that owns this agent (`tem_...`). `null` if the agent is not team-scoped.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "template_upgrade_available": { "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`).", "example": true, + "nullable": true, "type": "boolean" }, "updated_at": { "description": "When the agent was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "user": { "description": "ID of the user that owns this agent (`usr_...`). `null` if the agent is not user-scoped.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" } }, @@ -91538,16 +101080,19 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "role": { "description": "The authenticated user's membership role in this thread, e.g. `\"owner\"`, `\"member\"`, or `\"viewer\"`. `null` if the user is not a member.", "example": "member", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the developer sandbox this thread is scoped to (`dsb_...`). `null` for production threads.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "settings": { @@ -91557,8 +101102,9 @@ }, "properties": { "agent_enabled": { - "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.", + "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.", "example": true, + "nullable": true, "type": "boolean" } }, @@ -91567,6 +101113,7 @@ "slug": { "description": "URL-safe slug for the thread, used in human-readable permalinks. `null` if not assigned.", "example": "example-slug", + "nullable": true, "type": "string" }, "sub_threads": { @@ -91575,8 +101122,10 @@ {} ], "items": { + "nullable": true, "type": "object" }, + "nullable": true, "type": "array" }, "tags": { @@ -91593,32 +101142,36 @@ "team": { "description": "ID of the team that owns this thread (`team_...`). `null` for user-owned or agent-owned threads.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "title": { "description": "Human-readable name of the thread. `null` if no title has been set.", "example": "Example Title", + "nullable": true, "type": "string" }, "ttl": { - "description": "Time-to-live in seconds after which the thread may be automatically cleaned up. `null` if the thread does not expire.", - "example": 3600, - "type": "integer" + "description": "Offset-free expiry timestamp after which the thread may be automatically cleaned up. `null` if the thread does not expire.", + "example": "2026-08-15T12:00:00", + "nullable": true, + "type": "string" }, "unread_count": { "description": "Number of messages in this thread that the authenticated user has not yet read. Present only when read-state enrichment is requested.", "example": 5, + "nullable": true, "type": "integer" }, "updated_at": { "description": "When the thread was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "user": { "description": "ID of the user who owns this thread (`usr_...`). `null` for team-owned or agent-owned threads.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "visibility": { @@ -91825,7 +101378,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" } ] @@ -91967,7 +101520,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" } ], @@ -92074,7 +101627,7 @@ ], "branched_thread": "string", "content": "Hello, how can I help you today?", - "created_at": "2024-01-01T00:00:00Z", + "created_at": "string", "has_replies": true, "id": "msg_0aBcDeFgHiJkLmNoPqRsTu", "idempotency_key": "01234567-89ab-cdef-0123-456789abcdef", @@ -92233,7 +101786,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "root_message_id": "string", @@ -92241,7 +101794,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "properties": { @@ -92275,6 +101828,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -92456,16 +102010,19 @@ "alias": { "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", "example": "alice", + "nullable": true, "type": "string" }, "id": { "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "nullable": true, "type": "string" }, "name": { "description": "Display name of the actor shown in the UI. `null` if no name is set.", "example": "Example Name", + "nullable": true, "type": "string" }, "profile_picture": { @@ -92479,40 +102036,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -92526,6 +102091,7 @@ "agent": { "description": "ID of the agent user that sent this message (`agi_...`). `null` for messages sent by human users.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "agent_mode": { @@ -92535,6 +102101,7 @@ "embedded" ], "example": "cli", + "nullable": true, "type": "string" }, "attachments": { @@ -92647,21 +102214,25 @@ "content_type": { "description": "MIME type of the attached file, e.g. `\"image/png\"` or `\"application/pdf\"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.", "example": "application/json", + "nullable": true, "type": "string" }, "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "filename": { "description": "Original filename of the attached file, e.g. `\"report.pdf\"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.", "example": "string", + "nullable": true, "type": "string" }, "height": { "description": "Height in pixels of the media item. Present on `media` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "id": { @@ -92672,6 +102243,7 @@ "image_height": { "description": "Height in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "image_source": { @@ -92685,40 +102257,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -92727,31 +102307,35 @@ "image_url": { "description": "URL of the preview image extracted from the scraped page. Present on `scraped_link` type only. `null` otherwise.", "example": "https://example.com", + "nullable": true, "type": "string" }, "image_width": { "description": "Width in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "media_type": { - "description": "The media category, e.g. `\"video\"` or `\"audio\"`. Present on `media` type only. `null` otherwise.", + "description": "The media category, e.g. `\"video\"` or `\"audio\"`. Present on `media` type only; omitted otherwise.", "example": "application/json", "type": "string" }, "name": { "description": "Display name of the media item. Present on `media` type only. `null` otherwise.", "example": "Example Name", + "nullable": true, "type": "string" }, "object": { - "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`. `null` on other types.", + "description": "The full embedded object payload. For `task` type, contains the task record. For `action` type, contains the action definition. For `chart` type, contains the chart with its inline `spec`. Omitted on other types.", "example": {}, "type": "object" }, "title": { "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.", "example": "Example Title", + "nullable": true, "type": "string" }, "type": { @@ -92762,10 +102346,11 @@ "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "variants": { - "description": "Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only. `null` otherwise.", + "description": "Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only; omitted otherwise.", "example": [ { "content_type": "application/json", @@ -92816,6 +102401,7 @@ "content_type": { "description": "MIME type of this variant's file (e.g., `\"image/jpeg\"`, `\"video/mp4\"`). `null` if the file is not loaded.", "example": "application/json", + "nullable": true, "type": "string" }, "created_at": { @@ -92832,11 +102418,13 @@ "filename": { "description": "Original filename of the uploaded file for this variant. `null` if the file is not loaded.", "example": "string", + "nullable": true, "type": "string" }, "height": { "description": "Height of this variant in pixels. `null` if not recorded.", "example": 600, + "nullable": true, "type": "integer" }, "id": { @@ -92855,40 +102443,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -92903,6 +102499,7 @@ "url": { "description": "Signed download URL for this variant, resolved at request time. `null` if the file is unavailable.", "example": "https://example.com", + "nullable": true, "type": "string" }, "variant_key": { @@ -92913,6 +102510,7 @@ "width": { "description": "Width of this variant in pixels. `null` if not recorded.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -92926,11 +102524,13 @@ "version": { "description": "Version number of the attached artifact at the time of attachment. Present on `artifact` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "width": { "description": "Width in pixels of the media item. Present on `media` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" } }, @@ -92945,17 +102545,18 @@ "branched_thread": { "description": "ID of the thread that was branched from this message (`thr_...`). `null` if this message has not spawned a branch thread.", "example": "string", + "nullable": true, "type": "string" }, "content": { "description": "Text content of the message. `null` for messages that contain only attachments.", "example": "Hello, how can I help you today?", + "nullable": true, "type": "string" }, "created_at": { "description": "When the message was posted (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "has_replies": { @@ -92971,6 +102572,7 @@ "idempotency_key": { "description": "Client-supplied idempotency key used to deduplicate message sends. `null` if the sender did not provide one.", "example": "01234567-89ab-cdef-0123-456789abcdef", + "nullable": true, "type": "string" }, "is_deleted": { @@ -92981,6 +102583,7 @@ "legacy_agent": { "description": "Identifier of the legacy chat agent that sent this message, if applicable. `null` for messages sent by users or modern agent users.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -92993,6 +102596,7 @@ "org": { "description": "ID of the organization that owns this message (`org_...`).", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "reactions": { @@ -93044,6 +102648,7 @@ "rendering_mode": { "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.", "example": "reply", + "nullable": true, "type": "string" }, "replies": { @@ -93059,11 +102664,13 @@ "replies_after_cursor": { "description": "Opaque pagination cursor to fetch replies posted after the current page. Only present when inline replies are included in the response.", "example": "string", + "nullable": true, "type": "string" }, "replies_before_cursor": { "description": "Opaque pagination cursor to fetch replies posted before the current page. Only present when inline replies are included in the response.", "example": "string", + "nullable": true, "type": "string" }, "reply_count": { @@ -93206,9 +102813,10 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, + "nullable": true, "type": "object" }, "root_message_id": { @@ -93220,27 +102828,180 @@ "sandbox": { "description": "ID of the developer sandbox this message belongs to (`dsb_...`). `null` for non-sandbox messages.", "example": "string", + "nullable": true, "type": "string" }, "team": { "description": "ID of the team this message is scoped to (`tem_...`). `null` if the message is not team-scoped.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "thread": { - "description": "ID of the thread this message belongs to (`thr_...`). `null` for messages not yet associated with a thread.", + "description": "ID of the thread this message belongs to (`thr_...`).", "example": "string", "type": "string" }, "type": { "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.", "example": "note", + "nullable": true, "type": "string" }, "user": { "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.", - "example": "string", - "type": "string" + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "oneOf": [ + { + "type": "string" + }, + { + "description": "A platform user account. Represents a human or system actor that can own threads, belong to an organization, and interact with the API.", + "example": { + "alias": "jdoe", + "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "email": "user@example.com", + "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "is_system_user": true, + "metadata": { + "key": "value" + }, + "name": "Example Name", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "org_name": "Example Name", + "org_role": "member", + "org_slug": "example-slug", + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "sandbox_name": "Example Name" + }, + "properties": { + "alias": { + "description": "Short handle or alias for the user. `null` if not set.", + "example": "jdoe", + "nullable": true, + "type": "string" + }, + "app": { + "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.", + "example": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "app_name": { + "description": "Display name of the user's app. `null` when the app association was not preloaded by the caller.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "created_by_agent_user": { + "description": "Agent user that created this account (`usr_...`). `null` unless an agent created it.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_developer": { + "description": "Developer account that created this user (`dva_...`). `null` unless created via a developer token.", + "example": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_org": { + "description": "Org of the principal that created this user (`org_...`). `null` on legacy rows.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_team": { + "description": "Team that created this user (`tem_...`). `null` unless created as a team.", + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_user": { + "description": "User who created this account (`usr_...`). `null` on self-signup or legacy rows.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "email": { + "description": "Email address of the user.", + "example": "user@example.com", + "nullable": true, + "type": "string" + }, + "id": { + "description": "User ID (`usr_...`).", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "is_system_user": { + "description": "`true` if this account is an internal system user rather than a human. System users are created automatically by the platform.", + "example": true, + "type": "boolean" + }, + "metadata": { + "description": "Arbitrary key-value metadata attached to the user. Defaults to an empty object.", + "example": { + "key": "value" + }, + "type": "object" + }, + "name": { + "description": "Full display name of the user. `null` if the user has not set a name.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "org": { + "description": "ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "org_name": { + "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.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "org_role": { + "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.", + "example": "member", + "nullable": true, + "type": "string" + }, + "org_slug": { + "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.", + "example": "example-slug", + "nullable": true, + "type": "string" + }, + "sandbox": { + "description": "ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.", + "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "sandbox_name": { + "description": "Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.", + "example": "Example Name", + "nullable": true, + "type": "string" + } + }, + "required": [ + "id" + ], + "type": "object" + } + ] }, "visibility": { "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.", @@ -93673,6 +103434,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -93683,6 +103449,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -93822,7 +103589,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" } ], @@ -94024,7 +103791,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "participant": [ @@ -94035,6 +103802,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -94045,6 +103817,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -94250,7 +104023,7 @@ ], "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "title": "Example Title", - "ttl": 3600, + "ttl": "2026-08-15T12:00:00", "unread_count": 5, "updated_at": "2024-01-01T00:00:00Z", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", @@ -94635,6 +104408,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -94645,6 +104423,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -94784,7 +104563,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" } ], @@ -94986,7 +104765,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "participant": [ @@ -94997,6 +104776,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -95007,6 +104791,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -95212,7 +104997,7 @@ ], "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "title": "Example Title", - "ttl": 3600, + "ttl": "2026-08-15T12:00:00", "unread_count": 5, "updated_at": "2024-01-01T00:00:00Z", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", @@ -95439,6 +105224,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -95589,23 +105375,25 @@ }, "created_at": { "description": "When the agent was created (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "default_model": { "description": "Default LLM model identifier used by this agent when no model is specified at runtime (e.g. `\"claude-3-7-sonnet-latest\"`).", "example": "claude-3-7-sonnet-latest", + "nullable": true, "type": "string" }, "description": { "description": "Human-readable description of what the agent does. `null` if not set.", "example": "An example description.", + "nullable": true, "type": "string" }, "email": { "description": "Email address provisioned for this agent. `null` if email delivery is not configured.", "example": "user@example.com", + "nullable": true, "type": "string" }, "id": { @@ -95616,16 +105404,19 @@ "identity": { "description": "System-level identity prompt that shapes the agent's persona and behavior.", "example": "You are a helpful assistant that answers questions about ArchAstro products.", + "nullable": true, "type": "string" }, "last_applied_template_config": { "description": "ID of the AgentTemplate config (`cfg_...`) this agent was last provisioned or updated from. `null` for manually created agents.", "example": "cfg_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "lookup_key": { "description": "Stable, user-defined identifier for this agent within the application. Unique per app.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -95643,26 +105434,31 @@ "org": { "description": "ID of the organization this agent belongs to (`org_...`). `null` if the agent is not org-scoped.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_name": { "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.", "example": "Example Name", + "nullable": true, "type": "string" }, "originator": { "description": "Free-form label identifying the source or author that created this agent (e.g. a username or pipeline name).", "example": "deploy-pipeline", + "nullable": true, "type": "string" }, "phone_number": { "description": "Phone number provisioned for this agent. `null` if SMS is not configured.", "example": "+15555550123", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the sandbox environment this agent is scoped to (`dsb_...`). `null` in production deployments.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "source_solution": { @@ -95796,6 +105592,7 @@ "virtual_path": "string" } }, + "nullable": true, "properties": { "current_solution": { "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.", @@ -95870,13 +105667,13 @@ }, "created_at": { "description": "When the Solution config was first imported (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "events": { @@ -95892,6 +105689,7 @@ "image_url": { "description": "Absolute URL of the Solution's cover image — the bundled asset the body's `image:` field names. A stable, non-expiring capability URL (like `org_logo.url`), safe to hold in caches and OpenGraph tags; it 404s if the Solution stops declaring a cover. `null` when the Solution has no cover image, and always `null` for org-scoped rows — the permanent URL is minted for system-scope (catalog) Solutions only.", "example": "https://example.com", + "nullable": true, "type": "string" }, "kind": { @@ -95902,16 +105700,19 @@ "latest_solution": { "description": "When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "latest_version": { "description": "When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", "example": "1.0.0", + "nullable": true, "type": "string" }, "lookup_key": { "description": "The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -95924,11 +105725,13 @@ "name": { "description": "Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "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.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_logo": { @@ -95942,40 +105745,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -95984,11 +105795,13 @@ "org_name": { "description": "Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_slug": { "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.", "example": "example-slug", + "nullable": true, "type": "string" }, "owners": { @@ -96004,6 +105817,7 @@ "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "screenshot_urls": { @@ -96019,11 +105833,13 @@ "solution_id": { "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.", "example": "01234567-89ab-cdef-0123-456789abcdef", + "nullable": true, "type": "string" }, "solution_version": { "description": "Semver string declared in the Solution body (e.g. `\"1.2.0\"`). `null` when the body does not declare a version.", "example": "1.2.0", + "nullable": true, "type": "string" }, "tag_keys": { @@ -96039,6 +105855,7 @@ "template_kind": { "description": "Wrapped template kind — `\"AgentTemplate\"`, `\"AutomationTemplate\"`, `\"AgentRoutineTemplate\"`, `\"AgentToolTemplate\"`, `\"AgentComputerTemplate\"`, or `\"SolutionTemplateRef\"` for ref-mode bundles.", "example": "AgentTemplate", + "nullable": true, "type": "string" }, "templates": { @@ -96071,6 +105888,7 @@ "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "details": { @@ -96078,6 +105896,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -96102,12 +105921,13 @@ }, "properties": { "automation_type": { - "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`).", + "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", "example": "string", + "nullable": true, "type": "string" }, "invoke_contract": { - "description": "Schema-driven payload and participant inputs for an invoked automation. Used by installation clients to collect locked prefills before provisioning.", + "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.", "example": { "input_schema": {}, "participants": [ @@ -96123,10 +105943,12 @@ "payload": {} } }, + "nullable": true, "properties": { "input_schema": { "description": "JSON Schema validated against the whole invoke payload, from the automation's `input_schema_config`. `null` when none is configured.", "example": {}, + "nullable": true, "type": "object" }, "participants": { @@ -96147,10 +105969,12 @@ "required": true, "type": "agent_user" }, + "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", "example": "An example description.", + "nullable": true, "type": "string" }, "name": { @@ -96176,6 +106000,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -96224,11 +106049,13 @@ "display_name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "id": { "description": "Template config ID (`cfg_...`). `null` for inline-only templates.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "kind": { @@ -96239,21 +106066,25 @@ "lookup_key": { "description": "Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", "example": "string", + "nullable": true, "type": "string" }, "name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "virtual_path": { "description": "Stable virtual path assigned to the template config. `null` when no virtual path was set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -96266,8 +106097,7 @@ }, "updated_at": { "description": "When the Solution config was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "upgrade_available": { @@ -96278,6 +106108,7 @@ "virtual_path": { "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.", "example": "string", + "nullable": true, "type": "string" } }, @@ -96363,13 +106194,13 @@ }, "created_at": { "description": "When the Solution config was first imported (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "events": { @@ -96385,6 +106216,7 @@ "image_url": { "description": "Absolute URL of the Solution's cover image — the bundled asset the body's `image:` field names. A stable, non-expiring capability URL (like `org_logo.url`), safe to hold in caches and OpenGraph tags; it 404s if the Solution stops declaring a cover. `null` when the Solution has no cover image, and always `null` for org-scoped rows — the permanent URL is minted for system-scope (catalog) Solutions only.", "example": "https://example.com", + "nullable": true, "type": "string" }, "kind": { @@ -96395,16 +106227,19 @@ "latest_solution": { "description": "When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "latest_version": { "description": "When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", "example": "1.0.0", + "nullable": true, "type": "string" }, "lookup_key": { "description": "The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -96417,11 +106252,13 @@ "name": { "description": "Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "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.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_logo": { @@ -96435,40 +106272,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -96477,11 +106322,13 @@ "org_name": { "description": "Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_slug": { "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.", "example": "example-slug", + "nullable": true, "type": "string" }, "owners": { @@ -96497,6 +106344,7 @@ "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "screenshot_urls": { @@ -96512,11 +106360,13 @@ "solution_id": { "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.", "example": "01234567-89ab-cdef-0123-456789abcdef", + "nullable": true, "type": "string" }, "solution_version": { "description": "Semver string declared in the Solution body (e.g. `\"1.2.0\"`). `null` when the body does not declare a version.", "example": "1.2.0", + "nullable": true, "type": "string" }, "tag_keys": { @@ -96532,6 +106382,7 @@ "template_kind": { "description": "Wrapped template kind — `\"AgentTemplate\"`, `\"AutomationTemplate\"`, `\"AgentRoutineTemplate\"`, `\"AgentToolTemplate\"`, `\"AgentComputerTemplate\"`, or `\"SolutionTemplateRef\"` for ref-mode bundles.", "example": "AgentTemplate", + "nullable": true, "type": "string" }, "templates": { @@ -96564,6 +106415,7 @@ "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "details": { @@ -96571,6 +106423,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -96595,12 +106448,13 @@ }, "properties": { "automation_type": { - "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`).", + "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", "example": "string", + "nullable": true, "type": "string" }, "invoke_contract": { - "description": "Schema-driven payload and participant inputs for an invoked automation. Used by installation clients to collect locked prefills before provisioning.", + "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.", "example": { "input_schema": {}, "participants": [ @@ -96616,10 +106470,12 @@ "payload": {} } }, + "nullable": true, "properties": { "input_schema": { "description": "JSON Schema validated against the whole invoke payload, from the automation's `input_schema_config`. `null` when none is configured.", "example": {}, + "nullable": true, "type": "object" }, "participants": { @@ -96640,10 +106496,12 @@ "required": true, "type": "agent_user" }, + "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", "example": "An example description.", + "nullable": true, "type": "string" }, "name": { @@ -96669,6 +106527,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -96717,11 +106576,13 @@ "display_name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "id": { "description": "Template config ID (`cfg_...`). `null` for inline-only templates.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "kind": { @@ -96732,21 +106593,25 @@ "lookup_key": { "description": "Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", "example": "string", + "nullable": true, "type": "string" }, "name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "virtual_path": { "description": "Stable virtual path assigned to the template config. `null` when no virtual path was set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -96759,8 +106624,7 @@ }, "updated_at": { "description": "When the Solution config was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "upgrade_available": { @@ -96771,6 +106635,7 @@ "virtual_path": { "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.", "example": "string", + "nullable": true, "type": "string" } }, @@ -96806,11 +106671,13 @@ "description": { "description": "Description of the template from the config body. `null` if the current version has no `description` field.", "example": "An example description.", + "nullable": true, "type": "string" }, "display_name": { "description": "Human-readable display name from the config body. `null` if the current version has no `display_name` field.", "example": "Example Name", + "nullable": true, "type": "string" }, "id": { @@ -96826,11 +106693,13 @@ "lookup_key": { "description": "Stable lookup key assigned to this template config. `null` if no lookup key is set.", "example": "string", + "nullable": true, "type": "string" }, "name": { "description": "Template name as stored in the config body. `null` if the current version has no `name` field.", "example": "Example Name", + "nullable": true, "type": "string" }, "updated_at": { @@ -96842,6 +106711,7 @@ "virtual_path": { "description": "Virtual filesystem path for this template config. `null` if not set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -96861,22 +106731,24 @@ "team": { "description": "ID of the team that owns this agent (`tem_...`). `null` if the agent is not team-scoped.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "template_upgrade_available": { "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`).", "example": true, + "nullable": true, "type": "boolean" }, "updated_at": { "description": "When the agent was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "user": { "description": "ID of the user that owns this agent (`usr_...`). `null` if the agent is not user-scoped.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" } }, @@ -97086,6 +106958,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -97096,6 +106973,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -97291,6 +107169,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -97301,6 +107184,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -97520,6 +107404,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -97670,23 +107555,25 @@ }, "created_at": { "description": "When the agent was created (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "default_model": { "description": "Default LLM model identifier used by this agent when no model is specified at runtime (e.g. `\"claude-3-7-sonnet-latest\"`).", "example": "claude-3-7-sonnet-latest", + "nullable": true, "type": "string" }, "description": { "description": "Human-readable description of what the agent does. `null` if not set.", "example": "An example description.", + "nullable": true, "type": "string" }, "email": { "description": "Email address provisioned for this agent. `null` if email delivery is not configured.", "example": "user@example.com", + "nullable": true, "type": "string" }, "id": { @@ -97697,16 +107584,19 @@ "identity": { "description": "System-level identity prompt that shapes the agent's persona and behavior.", "example": "You are a helpful assistant that answers questions about ArchAstro products.", + "nullable": true, "type": "string" }, "last_applied_template_config": { "description": "ID of the AgentTemplate config (`cfg_...`) this agent was last provisioned or updated from. `null` for manually created agents.", "example": "cfg_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "lookup_key": { "description": "Stable, user-defined identifier for this agent within the application. Unique per app.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -97724,26 +107614,31 @@ "org": { "description": "ID of the organization this agent belongs to (`org_...`). `null` if the agent is not org-scoped.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_name": { "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.", "example": "Example Name", + "nullable": true, "type": "string" }, "originator": { "description": "Free-form label identifying the source or author that created this agent (e.g. a username or pipeline name).", "example": "deploy-pipeline", + "nullable": true, "type": "string" }, "phone_number": { "description": "Phone number provisioned for this agent. `null` if SMS is not configured.", "example": "+15555550123", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the sandbox environment this agent is scoped to (`dsb_...`). `null` in production deployments.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "source_solution": { @@ -97877,6 +107772,7 @@ "virtual_path": "string" } }, + "nullable": true, "properties": { "current_solution": { "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.", @@ -97951,13 +107847,13 @@ }, "created_at": { "description": "When the Solution config was first imported (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "events": { @@ -97973,6 +107869,7 @@ "image_url": { "description": "Absolute URL of the Solution's cover image — the bundled asset the body's `image:` field names. A stable, non-expiring capability URL (like `org_logo.url`), safe to hold in caches and OpenGraph tags; it 404s if the Solution stops declaring a cover. `null` when the Solution has no cover image, and always `null` for org-scoped rows — the permanent URL is minted for system-scope (catalog) Solutions only.", "example": "https://example.com", + "nullable": true, "type": "string" }, "kind": { @@ -97983,16 +107880,19 @@ "latest_solution": { "description": "When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "latest_version": { "description": "When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", "example": "1.0.0", + "nullable": true, "type": "string" }, "lookup_key": { "description": "The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -98005,11 +107905,13 @@ "name": { "description": "Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "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.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_logo": { @@ -98023,40 +107925,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -98065,11 +107975,13 @@ "org_name": { "description": "Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_slug": { "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.", "example": "example-slug", + "nullable": true, "type": "string" }, "owners": { @@ -98085,6 +107997,7 @@ "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "screenshot_urls": { @@ -98100,11 +108013,13 @@ "solution_id": { "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.", "example": "01234567-89ab-cdef-0123-456789abcdef", + "nullable": true, "type": "string" }, "solution_version": { "description": "Semver string declared in the Solution body (e.g. `\"1.2.0\"`). `null` when the body does not declare a version.", "example": "1.2.0", + "nullable": true, "type": "string" }, "tag_keys": { @@ -98120,6 +108035,7 @@ "template_kind": { "description": "Wrapped template kind — `\"AgentTemplate\"`, `\"AutomationTemplate\"`, `\"AgentRoutineTemplate\"`, `\"AgentToolTemplate\"`, `\"AgentComputerTemplate\"`, or `\"SolutionTemplateRef\"` for ref-mode bundles.", "example": "AgentTemplate", + "nullable": true, "type": "string" }, "templates": { @@ -98152,6 +108068,7 @@ "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "details": { @@ -98159,6 +108076,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -98183,12 +108101,13 @@ }, "properties": { "automation_type": { - "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`).", + "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", "example": "string", + "nullable": true, "type": "string" }, "invoke_contract": { - "description": "Schema-driven payload and participant inputs for an invoked automation. Used by installation clients to collect locked prefills before provisioning.", + "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.", "example": { "input_schema": {}, "participants": [ @@ -98204,10 +108123,12 @@ "payload": {} } }, + "nullable": true, "properties": { "input_schema": { "description": "JSON Schema validated against the whole invoke payload, from the automation's `input_schema_config`. `null` when none is configured.", "example": {}, + "nullable": true, "type": "object" }, "participants": { @@ -98228,10 +108149,12 @@ "required": true, "type": "agent_user" }, + "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", "example": "An example description.", + "nullable": true, "type": "string" }, "name": { @@ -98257,6 +108180,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -98305,11 +108229,13 @@ "display_name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "id": { "description": "Template config ID (`cfg_...`). `null` for inline-only templates.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "kind": { @@ -98320,21 +108246,25 @@ "lookup_key": { "description": "Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", "example": "string", + "nullable": true, "type": "string" }, "name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "virtual_path": { "description": "Stable virtual path assigned to the template config. `null` when no virtual path was set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -98347,8 +108277,7 @@ }, "updated_at": { "description": "When the Solution config was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "upgrade_available": { @@ -98359,6 +108288,7 @@ "virtual_path": { "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.", "example": "string", + "nullable": true, "type": "string" } }, @@ -98444,13 +108374,13 @@ }, "created_at": { "description": "When the Solution config was first imported (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "events": { @@ -98466,6 +108396,7 @@ "image_url": { "description": "Absolute URL of the Solution's cover image — the bundled asset the body's `image:` field names. A stable, non-expiring capability URL (like `org_logo.url`), safe to hold in caches and OpenGraph tags; it 404s if the Solution stops declaring a cover. `null` when the Solution has no cover image, and always `null` for org-scoped rows — the permanent URL is minted for system-scope (catalog) Solutions only.", "example": "https://example.com", + "nullable": true, "type": "string" }, "kind": { @@ -98476,16 +108407,19 @@ "latest_solution": { "description": "When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "latest_version": { "description": "When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", "example": "1.0.0", + "nullable": true, "type": "string" }, "lookup_key": { "description": "The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -98498,11 +108432,13 @@ "name": { "description": "Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "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.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_logo": { @@ -98516,40 +108452,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -98558,11 +108502,13 @@ "org_name": { "description": "Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_slug": { "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.", "example": "example-slug", + "nullable": true, "type": "string" }, "owners": { @@ -98578,6 +108524,7 @@ "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "screenshot_urls": { @@ -98593,11 +108540,13 @@ "solution_id": { "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.", "example": "01234567-89ab-cdef-0123-456789abcdef", + "nullable": true, "type": "string" }, "solution_version": { "description": "Semver string declared in the Solution body (e.g. `\"1.2.0\"`). `null` when the body does not declare a version.", "example": "1.2.0", + "nullable": true, "type": "string" }, "tag_keys": { @@ -98613,6 +108562,7 @@ "template_kind": { "description": "Wrapped template kind — `\"AgentTemplate\"`, `\"AutomationTemplate\"`, `\"AgentRoutineTemplate\"`, `\"AgentToolTemplate\"`, `\"AgentComputerTemplate\"`, or `\"SolutionTemplateRef\"` for ref-mode bundles.", "example": "AgentTemplate", + "nullable": true, "type": "string" }, "templates": { @@ -98645,6 +108595,7 @@ "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "details": { @@ -98652,6 +108603,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -98676,12 +108628,13 @@ }, "properties": { "automation_type": { - "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`).", + "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", "example": "string", + "nullable": true, "type": "string" }, "invoke_contract": { - "description": "Schema-driven payload and participant inputs for an invoked automation. Used by installation clients to collect locked prefills before provisioning.", + "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.", "example": { "input_schema": {}, "participants": [ @@ -98697,10 +108650,12 @@ "payload": {} } }, + "nullable": true, "properties": { "input_schema": { "description": "JSON Schema validated against the whole invoke payload, from the automation's `input_schema_config`. `null` when none is configured.", "example": {}, + "nullable": true, "type": "object" }, "participants": { @@ -98721,10 +108676,12 @@ "required": true, "type": "agent_user" }, + "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", "example": "An example description.", + "nullable": true, "type": "string" }, "name": { @@ -98750,6 +108707,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -98798,11 +108756,13 @@ "display_name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "id": { "description": "Template config ID (`cfg_...`). `null` for inline-only templates.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "kind": { @@ -98813,21 +108773,25 @@ "lookup_key": { "description": "Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", "example": "string", + "nullable": true, "type": "string" }, "name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "virtual_path": { "description": "Stable virtual path assigned to the template config. `null` when no virtual path was set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -98840,8 +108804,7 @@ }, "updated_at": { "description": "When the Solution config was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "upgrade_available": { @@ -98852,6 +108815,7 @@ "virtual_path": { "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.", "example": "string", + "nullable": true, "type": "string" } }, @@ -98887,11 +108851,13 @@ "description": { "description": "Description of the template from the config body. `null` if the current version has no `description` field.", "example": "An example description.", + "nullable": true, "type": "string" }, "display_name": { "description": "Human-readable display name from the config body. `null` if the current version has no `display_name` field.", "example": "Example Name", + "nullable": true, "type": "string" }, "id": { @@ -98907,11 +108873,13 @@ "lookup_key": { "description": "Stable lookup key assigned to this template config. `null` if no lookup key is set.", "example": "string", + "nullable": true, "type": "string" }, "name": { "description": "Template name as stored in the config body. `null` if the current version has no `name` field.", "example": "Example Name", + "nullable": true, "type": "string" }, "updated_at": { @@ -98923,6 +108891,7 @@ "virtual_path": { "description": "Virtual filesystem path for this template config. `null` if not set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -98942,22 +108911,24 @@ "team": { "description": "ID of the team that owns this agent (`tem_...`). `null` if the agent is not team-scoped.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "template_upgrade_available": { "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`).", "example": true, + "nullable": true, "type": "boolean" }, "updated_at": { "description": "When the agent was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "user": { "description": "ID of the user that owns this agent (`usr_...`). `null` if the agent is not user-scoped.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" } }, @@ -98982,6 +108953,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -98992,6 +108968,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" }, @@ -98999,21 +108976,55 @@ "alias": { "description": "Short handle or alias for the user. `null` if not set.", "example": "jdoe", + "nullable": true, "type": "string" }, "app": { "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.", "example": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "app_name": { "description": "Display name of the user's app. `null` when the app association was not preloaded by the caller.", "example": "Example Name", + "nullable": true, + "type": "string" + }, + "created_by_agent_user": { + "description": "Agent user that created this account (`usr_...`). `null` unless an agent created it.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_developer": { + "description": "Developer account that created this user (`dva_...`). `null` unless created via a developer token.", + "example": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_org": { + "description": "Org of the principal that created this user (`org_...`). `null` on legacy rows.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_team": { + "description": "Team that created this user (`tem_...`). `null` unless created as a team.", + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_user": { + "description": "User who created this account (`usr_...`). `null` on self-signup or legacy rows.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "email": { "description": "Email address of the user.", "example": "user@example.com", + "nullable": true, "type": "string" }, "id": { @@ -99036,31 +109047,43 @@ "name": { "description": "Full display name of the user. `null` if the user has not set a name.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "description": "ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_name": { "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.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_role": { "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.", "example": "member", + "nullable": true, + "type": "string" + }, + "org_slug": { + "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.", + "example": "example-slug", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "sandbox_name": { "description": "Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.", "example": "Example Name", + "nullable": true, "type": "string" } }, @@ -99213,7 +109236,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" } ], @@ -99320,7 +109343,7 @@ ], "branched_thread": "string", "content": "Hello, how can I help you today?", - "created_at": "2024-01-01T00:00:00Z", + "created_at": "string", "has_replies": true, "id": "msg_0aBcDeFgHiJkLmNoPqRsTu", "idempotency_key": "01234567-89ab-cdef-0123-456789abcdef", @@ -99479,7 +109502,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "root_message_id": "string", @@ -99487,7 +109510,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "properties": { @@ -99521,6 +109544,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -99702,16 +109726,19 @@ "alias": { "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", "example": "alice", + "nullable": true, "type": "string" }, "id": { "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "nullable": true, "type": "string" }, "name": { "description": "Display name of the actor shown in the UI. `null` if no name is set.", "example": "Example Name", + "nullable": true, "type": "string" }, "profile_picture": { @@ -99725,40 +109752,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -99772,6 +109807,7 @@ "agent": { "description": "ID of the agent user that sent this message (`agi_...`). `null` for messages sent by human users.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "agent_mode": { @@ -99781,6 +109817,7 @@ "embedded" ], "example": "cli", + "nullable": true, "type": "string" }, "attachments": { @@ -99893,21 +109930,25 @@ "content_type": { "description": "MIME type of the attached file, e.g. `\"image/png\"` or `\"application/pdf\"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.", "example": "application/json", + "nullable": true, "type": "string" }, "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "filename": { "description": "Original filename of the attached file, e.g. `\"report.pdf\"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.", "example": "string", + "nullable": true, "type": "string" }, "height": { "description": "Height in pixels of the media item. Present on `media` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "id": { @@ -99918,6 +109959,7 @@ "image_height": { "description": "Height in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "image_source": { @@ -99931,40 +109973,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -99973,31 +110023,35 @@ "image_url": { "description": "URL of the preview image extracted from the scraped page. Present on `scraped_link` type only. `null` otherwise.", "example": "https://example.com", + "nullable": true, "type": "string" }, "image_width": { "description": "Width in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "media_type": { - "description": "The media category, e.g. `\"video\"` or `\"audio\"`. Present on `media` type only. `null` otherwise.", + "description": "The media category, e.g. `\"video\"` or `\"audio\"`. Present on `media` type only; omitted otherwise.", "example": "application/json", "type": "string" }, "name": { "description": "Display name of the media item. Present on `media` type only. `null` otherwise.", "example": "Example Name", + "nullable": true, "type": "string" }, "object": { - "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`. `null` on other types.", + "description": "The full embedded object payload. For `task` type, contains the task record. For `action` type, contains the action definition. For `chart` type, contains the chart with its inline `spec`. Omitted on other types.", "example": {}, "type": "object" }, "title": { "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.", "example": "Example Title", + "nullable": true, "type": "string" }, "type": { @@ -100008,10 +110062,11 @@ "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "variants": { - "description": "Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only. `null` otherwise.", + "description": "Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only; omitted otherwise.", "example": [ { "content_type": "application/json", @@ -100062,6 +110117,7 @@ "content_type": { "description": "MIME type of this variant's file (e.g., `\"image/jpeg\"`, `\"video/mp4\"`). `null` if the file is not loaded.", "example": "application/json", + "nullable": true, "type": "string" }, "created_at": { @@ -100078,11 +110134,13 @@ "filename": { "description": "Original filename of the uploaded file for this variant. `null` if the file is not loaded.", "example": "string", + "nullable": true, "type": "string" }, "height": { "description": "Height of this variant in pixels. `null` if not recorded.", "example": 600, + "nullable": true, "type": "integer" }, "id": { @@ -100101,40 +110159,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -100149,6 +110215,7 @@ "url": { "description": "Signed download URL for this variant, resolved at request time. `null` if the file is unavailable.", "example": "https://example.com", + "nullable": true, "type": "string" }, "variant_key": { @@ -100159,6 +110226,7 @@ "width": { "description": "Width of this variant in pixels. `null` if not recorded.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -100172,11 +110240,13 @@ "version": { "description": "Version number of the attached artifact at the time of attachment. Present on `artifact` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "width": { "description": "Width in pixels of the media item. Present on `media` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" } }, @@ -100191,17 +110261,18 @@ "branched_thread": { "description": "ID of the thread that was branched from this message (`thr_...`). `null` if this message has not spawned a branch thread.", "example": "string", + "nullable": true, "type": "string" }, "content": { "description": "Text content of the message. `null` for messages that contain only attachments.", "example": "Hello, how can I help you today?", + "nullable": true, "type": "string" }, "created_at": { "description": "When the message was posted (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "has_replies": { @@ -100217,6 +110288,7 @@ "idempotency_key": { "description": "Client-supplied idempotency key used to deduplicate message sends. `null` if the sender did not provide one.", "example": "01234567-89ab-cdef-0123-456789abcdef", + "nullable": true, "type": "string" }, "is_deleted": { @@ -100227,6 +110299,7 @@ "legacy_agent": { "description": "Identifier of the legacy chat agent that sent this message, if applicable. `null` for messages sent by users or modern agent users.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -100239,6 +110312,7 @@ "org": { "description": "ID of the organization that owns this message (`org_...`).", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "reactions": { @@ -100290,6 +110364,7 @@ "rendering_mode": { "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.", "example": "reply", + "nullable": true, "type": "string" }, "replies": { @@ -100305,11 +110380,13 @@ "replies_after_cursor": { "description": "Opaque pagination cursor to fetch replies posted after the current page. Only present when inline replies are included in the response.", "example": "string", + "nullable": true, "type": "string" }, "replies_before_cursor": { "description": "Opaque pagination cursor to fetch replies posted before the current page. Only present when inline replies are included in the response.", "example": "string", + "nullable": true, "type": "string" }, "reply_count": { @@ -100452,9 +110529,10 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, + "nullable": true, "type": "object" }, "root_message_id": { @@ -100466,27 +110544,180 @@ "sandbox": { "description": "ID of the developer sandbox this message belongs to (`dsb_...`). `null` for non-sandbox messages.", "example": "string", + "nullable": true, "type": "string" }, "team": { "description": "ID of the team this message is scoped to (`tem_...`). `null` if the message is not team-scoped.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "thread": { - "description": "ID of the thread this message belongs to (`thr_...`). `null` for messages not yet associated with a thread.", + "description": "ID of the thread this message belongs to (`thr_...`).", "example": "string", "type": "string" }, "type": { "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.", "example": "note", + "nullable": true, "type": "string" }, "user": { "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.", - "example": "string", - "type": "string" + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "oneOf": [ + { + "type": "string" + }, + { + "description": "A platform user account. Represents a human or system actor that can own threads, belong to an organization, and interact with the API.", + "example": { + "alias": "jdoe", + "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "email": "user@example.com", + "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "is_system_user": true, + "metadata": { + "key": "value" + }, + "name": "Example Name", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "org_name": "Example Name", + "org_role": "member", + "org_slug": "example-slug", + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "sandbox_name": "Example Name" + }, + "properties": { + "alias": { + "description": "Short handle or alias for the user. `null` if not set.", + "example": "jdoe", + "nullable": true, + "type": "string" + }, + "app": { + "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.", + "example": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "app_name": { + "description": "Display name of the user's app. `null` when the app association was not preloaded by the caller.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "created_by_agent_user": { + "description": "Agent user that created this account (`usr_...`). `null` unless an agent created it.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_developer": { + "description": "Developer account that created this user (`dva_...`). `null` unless created via a developer token.", + "example": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_org": { + "description": "Org of the principal that created this user (`org_...`). `null` on legacy rows.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_team": { + "description": "Team that created this user (`tem_...`). `null` unless created as a team.", + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_user": { + "description": "User who created this account (`usr_...`). `null` on self-signup or legacy rows.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "email": { + "description": "Email address of the user.", + "example": "user@example.com", + "nullable": true, + "type": "string" + }, + "id": { + "description": "User ID (`usr_...`).", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "is_system_user": { + "description": "`true` if this account is an internal system user rather than a human. System users are created automatically by the platform.", + "example": true, + "type": "boolean" + }, + "metadata": { + "description": "Arbitrary key-value metadata attached to the user. Defaults to an empty object.", + "example": { + "key": "value" + }, + "type": "object" + }, + "name": { + "description": "Full display name of the user. `null` if the user has not set a name.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "org": { + "description": "ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "org_name": { + "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.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "org_role": { + "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.", + "example": "member", + "nullable": true, + "type": "string" + }, + "org_slug": { + "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.", + "example": "example-slug", + "nullable": true, + "type": "string" + }, + "sandbox": { + "description": "ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.", + "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "sandbox_name": { + "description": "Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.", + "example": "Example Name", + "nullable": true, + "type": "string" + } + }, + "required": [ + "id" + ], + "type": "object" + } + ] }, "visibility": { "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.", @@ -100587,6 +110818,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -100738,6 +110970,7 @@ "badges": { "description": "Aggregated badge counts for the team, keyed by category. `null` when badge data is not loaded.", "example": {}, + "nullable": true, "type": "object" }, "created_at": { @@ -100749,6 +110982,7 @@ "description": { "description": "Human-readable description of the team's purpose. `null` if not set.", "example": "An example description.", + "nullable": true, "type": "string" }, "id": { @@ -100759,6 +110993,7 @@ "membership_status": { "description": "The authenticated viewer's role on this team. One of `\"owner\"`, `\"admin\"`, or `\"member\"`. `null` if the viewer is not a member.", "example": "member", + "nullable": true, "type": "string" }, "metadata": { @@ -100776,16 +111011,19 @@ "org": { "description": "ID of the organization this team belongs to (`org_...`). `null` if the team is not org-scoped.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the developer sandbox this team is scoped to (`dsb_...`). `null` outside sandbox contexts.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "slug": { "description": "URL-safe slug for the team, derived from the team name. `null` if not set.", "example": "example-slug", + "nullable": true, "type": "string" }, "updated_at": { @@ -100955,7 +111193,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "participant": [ @@ -100966,6 +111204,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -100976,6 +111219,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -101181,7 +111425,7 @@ ], "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "title": "Example Title", - "ttl": 3600, + "ttl": "2026-08-15T12:00:00", "unread_count": 5, "updated_at": "2024-01-01T00:00:00Z", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", @@ -101191,17 +111435,18 @@ "agent_user": { "description": "ID of the agent that owns this thread (`agt_...`). `null` for user-owned or team-owned threads.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "created_at": { "description": "When the thread was created (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "creator": { "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.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "oneOf": [ { "type": "string" @@ -101212,6 +111457,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -101222,6 +111472,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" }, @@ -101229,21 +111480,55 @@ "alias": { "description": "Short handle or alias for the user. `null` if not set.", "example": "jdoe", + "nullable": true, "type": "string" }, "app": { "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.", "example": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "app_name": { "description": "Display name of the user's app. `null` when the app association was not preloaded by the caller.", "example": "Example Name", + "nullable": true, + "type": "string" + }, + "created_by_agent_user": { + "description": "Agent user that created this account (`usr_...`). `null` unless an agent created it.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_developer": { + "description": "Developer account that created this user (`dva_...`). `null` unless created via a developer token.", + "example": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_org": { + "description": "Org of the principal that created this user (`org_...`). `null` on legacy rows.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_team": { + "description": "Team that created this user (`tem_...`). `null` unless created as a team.", + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_user": { + "description": "User who created this account (`usr_...`). `null` on self-signup or legacy rows.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "email": { "description": "Email address of the user.", "example": "user@example.com", + "nullable": true, "type": "string" }, "id": { @@ -101266,31 +111551,43 @@ "name": { "description": "Full display name of the user. `null` if the user has not set a name.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "description": "ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_name": { "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.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_role": { "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.", "example": "member", + "nullable": true, + "type": "string" + }, + "org_slug": { + "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.", + "example": "example-slug", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "sandbox_name": { "description": "Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.", "example": "Example Name", + "nullable": true, "type": "string" } }, @@ -101304,6 +111601,7 @@ "description": { "description": "Optional description or purpose statement for the thread. `null` if not set.", "example": "An example description.", + "nullable": true, "type": "string" }, "id": { @@ -101334,27 +111632,31 @@ "key": { "description": "Application-defined stable key that uniquely identifies the thread within its scope. Useful for idempotent creation. `null` if not set.", "example": "string", + "nullable": true, "type": "string" }, "kind": { - "description": "Thread subtype: `\"standard\"` for ordinary threads, `\"slack_mirror\"` for the membership-strict mirror of a Slack channel, `\"slashwork_mirror\"` for the membership-strict mirror of a Slashwork group. Read-only — derived server-side at creation, never accepted from params.", + "description": "Thread subtype: `\"standard\"` for ordinary threads, `\"personal\"` for a user-and-owned-agents roster, `\"slack_mirror\"` for the membership-strict mirror of a Slack channel, or `\"slashwork_mirror\"` for the membership-strict mirror of a Slashwork group. `personal` is an explicit user-thread creation option; mirror kinds are server-derived.", "example": "string", + "nullable": true, "type": "string" }, "last_activity": { "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.", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", + "nullable": true, "type": "string" }, "last_message_preview": { "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.", "example": "Sounds good — I'll ship the fix tomorrow.", + "nullable": true, "type": "string" }, "last_message_sender": { "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.", "example": "Alice Chen", + "nullable": true, "type": "string" }, "metadata": { @@ -101362,6 +111664,7 @@ "example": { "key": "value" }, + "nullable": true, "type": "object" }, "muted": { @@ -101372,6 +111675,7 @@ "org": { "description": "ID of the organization this thread belongs to (`org_...`). `null` for threads outside an org context.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "parent_message": { @@ -101509,9 +111813,10 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, + "nullable": true, "properties": { "acl": { "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.", @@ -101543,6 +111848,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -101724,16 +112030,19 @@ "alias": { "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", "example": "alice", + "nullable": true, "type": "string" }, "id": { "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "nullable": true, "type": "string" }, "name": { "description": "Display name of the actor shown in the UI. `null` if no name is set.", "example": "Example Name", + "nullable": true, "type": "string" }, "profile_picture": { @@ -101747,40 +112056,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -101794,6 +112111,7 @@ "agent": { "description": "ID of the agent user that sent this message (`agi_...`). `null` for messages sent by human users.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "agent_mode": { @@ -101803,6 +112121,7 @@ "embedded" ], "example": "cli", + "nullable": true, "type": "string" }, "attachments": { @@ -101915,21 +112234,25 @@ "content_type": { "description": "MIME type of the attached file, e.g. `\"image/png\"` or `\"application/pdf\"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.", "example": "application/json", + "nullable": true, "type": "string" }, "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "filename": { "description": "Original filename of the attached file, e.g. `\"report.pdf\"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.", "example": "string", + "nullable": true, "type": "string" }, "height": { "description": "Height in pixels of the media item. Present on `media` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "id": { @@ -101940,6 +112263,7 @@ "image_height": { "description": "Height in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "image_source": { @@ -101953,40 +112277,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -101995,31 +112327,35 @@ "image_url": { "description": "URL of the preview image extracted from the scraped page. Present on `scraped_link` type only. `null` otherwise.", "example": "https://example.com", + "nullable": true, "type": "string" }, "image_width": { "description": "Width in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "media_type": { - "description": "The media category, e.g. `\"video\"` or `\"audio\"`. Present on `media` type only. `null` otherwise.", + "description": "The media category, e.g. `\"video\"` or `\"audio\"`. Present on `media` type only; omitted otherwise.", "example": "application/json", "type": "string" }, "name": { "description": "Display name of the media item. Present on `media` type only. `null` otherwise.", "example": "Example Name", + "nullable": true, "type": "string" }, "object": { - "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`. `null` on other types.", + "description": "The full embedded object payload. For `task` type, contains the task record. For `action` type, contains the action definition. For `chart` type, contains the chart with its inline `spec`. Omitted on other types.", "example": {}, "type": "object" }, "title": { "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.", "example": "Example Title", + "nullable": true, "type": "string" }, "type": { @@ -102030,10 +112366,11 @@ "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "variants": { - "description": "Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only. `null` otherwise.", + "description": "Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only; omitted otherwise.", "example": [ { "content_type": "application/json", @@ -102084,6 +112421,7 @@ "content_type": { "description": "MIME type of this variant's file (e.g., `\"image/jpeg\"`, `\"video/mp4\"`). `null` if the file is not loaded.", "example": "application/json", + "nullable": true, "type": "string" }, "created_at": { @@ -102100,11 +112438,13 @@ "filename": { "description": "Original filename of the uploaded file for this variant. `null` if the file is not loaded.", "example": "string", + "nullable": true, "type": "string" }, "height": { "description": "Height of this variant in pixels. `null` if not recorded.", "example": 600, + "nullable": true, "type": "integer" }, "id": { @@ -102123,40 +112463,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -102171,6 +112519,7 @@ "url": { "description": "Signed download URL for this variant, resolved at request time. `null` if the file is unavailable.", "example": "https://example.com", + "nullable": true, "type": "string" }, "variant_key": { @@ -102181,6 +112530,7 @@ "width": { "description": "Width of this variant in pixels. `null` if not recorded.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -102194,11 +112544,13 @@ "version": { "description": "Version number of the attached artifact at the time of attachment. Present on `artifact` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "width": { "description": "Width in pixels of the media item. Present on `media` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" } }, @@ -102213,17 +112565,18 @@ "branched_thread": { "description": "ID of the thread that was branched from this message (`thr_...`). `null` if this message has not spawned a branch thread.", "example": "string", + "nullable": true, "type": "string" }, "content": { "description": "Text content of the message. `null` for messages that contain only attachments.", "example": "Hello, how can I help you today?", + "nullable": true, "type": "string" }, "created_at": { "description": "When the message was posted (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "has_replies": { @@ -102239,6 +112592,7 @@ "idempotency_key": { "description": "Client-supplied idempotency key used to deduplicate message sends. `null` if the sender did not provide one.", "example": "01234567-89ab-cdef-0123-456789abcdef", + "nullable": true, "type": "string" }, "is_deleted": { @@ -102249,6 +112603,7 @@ "legacy_agent": { "description": "Identifier of the legacy chat agent that sent this message, if applicable. `null` for messages sent by users or modern agent users.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -102261,6 +112616,7 @@ "org": { "description": "ID of the organization that owns this message (`org_...`).", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "reactions": { @@ -102312,6 +112668,7 @@ "rendering_mode": { "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.", "example": "reply", + "nullable": true, "type": "string" }, "replies": { @@ -102327,11 +112684,13 @@ "replies_after_cursor": { "description": "Opaque pagination cursor to fetch replies posted after the current page. Only present when inline replies are included in the response.", "example": "string", + "nullable": true, "type": "string" }, "replies_before_cursor": { "description": "Opaque pagination cursor to fetch replies posted before the current page. Only present when inline replies are included in the response.", "example": "string", + "nullable": true, "type": "string" }, "reply_count": { @@ -102474,9 +112833,10 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, + "nullable": true, "type": "object" }, "root_message_id": { @@ -102488,27 +112848,180 @@ "sandbox": { "description": "ID of the developer sandbox this message belongs to (`dsb_...`). `null` for non-sandbox messages.", "example": "string", + "nullable": true, "type": "string" }, "team": { "description": "ID of the team this message is scoped to (`tem_...`). `null` if the message is not team-scoped.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "thread": { - "description": "ID of the thread this message belongs to (`thr_...`). `null` for messages not yet associated with a thread.", + "description": "ID of the thread this message belongs to (`thr_...`).", "example": "string", "type": "string" }, "type": { "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.", "example": "note", + "nullable": true, "type": "string" }, "user": { "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.", - "example": "string", - "type": "string" + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "oneOf": [ + { + "type": "string" + }, + { + "description": "A platform user account. Represents a human or system actor that can own threads, belong to an organization, and interact with the API.", + "example": { + "alias": "jdoe", + "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "email": "user@example.com", + "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "is_system_user": true, + "metadata": { + "key": "value" + }, + "name": "Example Name", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "org_name": "Example Name", + "org_role": "member", + "org_slug": "example-slug", + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "sandbox_name": "Example Name" + }, + "properties": { + "alias": { + "description": "Short handle or alias for the user. `null` if not set.", + "example": "jdoe", + "nullable": true, + "type": "string" + }, + "app": { + "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.", + "example": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "app_name": { + "description": "Display name of the user's app. `null` when the app association was not preloaded by the caller.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "created_by_agent_user": { + "description": "Agent user that created this account (`usr_...`). `null` unless an agent created it.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_developer": { + "description": "Developer account that created this user (`dva_...`). `null` unless created via a developer token.", + "example": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_org": { + "description": "Org of the principal that created this user (`org_...`). `null` on legacy rows.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_team": { + "description": "Team that created this user (`tem_...`). `null` unless created as a team.", + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_user": { + "description": "User who created this account (`usr_...`). `null` on self-signup or legacy rows.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "email": { + "description": "Email address of the user.", + "example": "user@example.com", + "nullable": true, + "type": "string" + }, + "id": { + "description": "User ID (`usr_...`).", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "is_system_user": { + "description": "`true` if this account is an internal system user rather than a human. System users are created automatically by the platform.", + "example": true, + "type": "boolean" + }, + "metadata": { + "description": "Arbitrary key-value metadata attached to the user. Defaults to an empty object.", + "example": { + "key": "value" + }, + "type": "object" + }, + "name": { + "description": "Full display name of the user. `null` if the user has not set a name.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "org": { + "description": "ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "org_name": { + "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.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "org_role": { + "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.", + "example": "member", + "nullable": true, + "type": "string" + }, + "org_slug": { + "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.", + "example": "example-slug", + "nullable": true, + "type": "string" + }, + "sandbox": { + "description": "ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.", + "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "sandbox_name": { + "description": "Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.", + "example": "Example Name", + "nullable": true, + "type": "string" + } + }, + "required": [ + "id" + ], + "type": "object" + } + ] }, "visibility": { "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.", @@ -102542,6 +113055,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -102552,6 +113070,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -102562,6 +113081,11 @@ "alias": "jdoe", "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "email": "user@example.com", "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", "is_system_user": true, @@ -102572,6 +113096,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" }, @@ -102579,21 +113104,55 @@ "alias": { "description": "Short handle or alias for the user. `null` if not set.", "example": "jdoe", + "nullable": true, "type": "string" }, "app": { "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.", "example": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "app_name": { "description": "Display name of the user's app. `null` when the app association was not preloaded by the caller.", "example": "Example Name", + "nullable": true, + "type": "string" + }, + "created_by_agent_user": { + "description": "Agent user that created this account (`usr_...`). `null` unless an agent created it.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_developer": { + "description": "Developer account that created this user (`dva_...`). `null` unless created via a developer token.", + "example": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_org": { + "description": "Org of the principal that created this user (`org_...`). `null` on legacy rows.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_team": { + "description": "Team that created this user (`tem_...`). `null` unless created as a team.", + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_user": { + "description": "User who created this account (`usr_...`). `null` on self-signup or legacy rows.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "email": { "description": "Email address of the user.", "example": "user@example.com", + "nullable": true, "type": "string" }, "id": { @@ -102616,31 +113175,43 @@ "name": { "description": "Full display name of the user. `null` if the user has not set a name.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "description": "ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_name": { "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.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_role": { "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.", "example": "member", + "nullable": true, + "type": "string" + }, + "org_slug": { + "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.", + "example": "example-slug", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "sandbox_name": { "description": "Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.", "example": "Example Name", + "nullable": true, "type": "string" } }, @@ -102878,7 +113449,7 @@ ] }, "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", - "created_at": "2024-01-01T00:00:00Z", + "created_at": "string", "default_model": "claude-3-7-sonnet-latest", "description": "An example description.", "email": "user@example.com", @@ -103026,9 +113597,10 @@ }, "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "template_upgrade_available": true, - "updated_at": "2024-01-01T00:00:00Z", + "updated_at": "string", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" }, + "nullable": true, "properties": { "acl": { "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.", @@ -103060,6 +113632,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -103210,23 +113783,25 @@ }, "created_at": { "description": "When the agent was created (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "default_model": { "description": "Default LLM model identifier used by this agent when no model is specified at runtime (e.g. `\"claude-3-7-sonnet-latest\"`).", "example": "claude-3-7-sonnet-latest", + "nullable": true, "type": "string" }, "description": { "description": "Human-readable description of what the agent does. `null` if not set.", "example": "An example description.", + "nullable": true, "type": "string" }, "email": { "description": "Email address provisioned for this agent. `null` if email delivery is not configured.", "example": "user@example.com", + "nullable": true, "type": "string" }, "id": { @@ -103237,16 +113812,19 @@ "identity": { "description": "System-level identity prompt that shapes the agent's persona and behavior.", "example": "You are a helpful assistant that answers questions about ArchAstro products.", + "nullable": true, "type": "string" }, "last_applied_template_config": { "description": "ID of the AgentTemplate config (`cfg_...`) this agent was last provisioned or updated from. `null` for manually created agents.", "example": "cfg_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "lookup_key": { "description": "Stable, user-defined identifier for this agent within the application. Unique per app.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -103264,26 +113842,31 @@ "org": { "description": "ID of the organization this agent belongs to (`org_...`). `null` if the agent is not org-scoped.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_name": { "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.", "example": "Example Name", + "nullable": true, "type": "string" }, "originator": { "description": "Free-form label identifying the source or author that created this agent (e.g. a username or pipeline name).", "example": "deploy-pipeline", + "nullable": true, "type": "string" }, "phone_number": { "description": "Phone number provisioned for this agent. `null` if SMS is not configured.", "example": "+15555550123", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the sandbox environment this agent is scoped to (`dsb_...`). `null` in production deployments.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "source_solution": { @@ -103417,6 +114000,7 @@ "virtual_path": "string" } }, + "nullable": true, "properties": { "current_solution": { "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.", @@ -103491,13 +114075,13 @@ }, "created_at": { "description": "When the Solution config was first imported (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "events": { @@ -103513,6 +114097,7 @@ "image_url": { "description": "Absolute URL of the Solution's cover image — the bundled asset the body's `image:` field names. A stable, non-expiring capability URL (like `org_logo.url`), safe to hold in caches and OpenGraph tags; it 404s if the Solution stops declaring a cover. `null` when the Solution has no cover image, and always `null` for org-scoped rows — the permanent URL is minted for system-scope (catalog) Solutions only.", "example": "https://example.com", + "nullable": true, "type": "string" }, "kind": { @@ -103523,16 +114108,19 @@ "latest_solution": { "description": "When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "latest_version": { "description": "When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", "example": "1.0.0", + "nullable": true, "type": "string" }, "lookup_key": { "description": "The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -103545,11 +114133,13 @@ "name": { "description": "Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "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.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_logo": { @@ -103563,40 +114153,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -103605,11 +114203,13 @@ "org_name": { "description": "Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_slug": { "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.", "example": "example-slug", + "nullable": true, "type": "string" }, "owners": { @@ -103625,6 +114225,7 @@ "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "screenshot_urls": { @@ -103640,11 +114241,13 @@ "solution_id": { "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.", "example": "01234567-89ab-cdef-0123-456789abcdef", + "nullable": true, "type": "string" }, "solution_version": { "description": "Semver string declared in the Solution body (e.g. `\"1.2.0\"`). `null` when the body does not declare a version.", "example": "1.2.0", + "nullable": true, "type": "string" }, "tag_keys": { @@ -103660,6 +114263,7 @@ "template_kind": { "description": "Wrapped template kind — `\"AgentTemplate\"`, `\"AutomationTemplate\"`, `\"AgentRoutineTemplate\"`, `\"AgentToolTemplate\"`, `\"AgentComputerTemplate\"`, or `\"SolutionTemplateRef\"` for ref-mode bundles.", "example": "AgentTemplate", + "nullable": true, "type": "string" }, "templates": { @@ -103692,6 +114296,7 @@ "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "details": { @@ -103699,6 +114304,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -103723,12 +114329,13 @@ }, "properties": { "automation_type": { - "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`).", + "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", "example": "string", + "nullable": true, "type": "string" }, "invoke_contract": { - "description": "Schema-driven payload and participant inputs for an invoked automation. Used by installation clients to collect locked prefills before provisioning.", + "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.", "example": { "input_schema": {}, "participants": [ @@ -103744,10 +114351,12 @@ "payload": {} } }, + "nullable": true, "properties": { "input_schema": { "description": "JSON Schema validated against the whole invoke payload, from the automation's `input_schema_config`. `null` when none is configured.", "example": {}, + "nullable": true, "type": "object" }, "participants": { @@ -103768,10 +114377,12 @@ "required": true, "type": "agent_user" }, + "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", "example": "An example description.", + "nullable": true, "type": "string" }, "name": { @@ -103797,6 +114408,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -103845,11 +114457,13 @@ "display_name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "id": { "description": "Template config ID (`cfg_...`). `null` for inline-only templates.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "kind": { @@ -103860,21 +114474,25 @@ "lookup_key": { "description": "Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", "example": "string", + "nullable": true, "type": "string" }, "name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "virtual_path": { "description": "Stable virtual path assigned to the template config. `null` when no virtual path was set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -103887,8 +114505,7 @@ }, "updated_at": { "description": "When the Solution config was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "upgrade_available": { @@ -103899,6 +114516,7 @@ "virtual_path": { "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.", "example": "string", + "nullable": true, "type": "string" } }, @@ -103984,13 +114602,13 @@ }, "created_at": { "description": "When the Solution config was first imported (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "events": { @@ -104006,6 +114624,7 @@ "image_url": { "description": "Absolute URL of the Solution's cover image — the bundled asset the body's `image:` field names. A stable, non-expiring capability URL (like `org_logo.url`), safe to hold in caches and OpenGraph tags; it 404s if the Solution stops declaring a cover. `null` when the Solution has no cover image, and always `null` for org-scoped rows — the permanent URL is minted for system-scope (catalog) Solutions only.", "example": "https://example.com", + "nullable": true, "type": "string" }, "kind": { @@ -104016,16 +114635,19 @@ "latest_solution": { "description": "When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "latest_version": { "description": "When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", "example": "1.0.0", + "nullable": true, "type": "string" }, "lookup_key": { "description": "The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -104038,11 +114660,13 @@ "name": { "description": "Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", "example": "Example Name", + "nullable": true, "type": "string" }, "org": { "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.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "org_logo": { @@ -104056,40 +114680,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -104098,11 +114730,13 @@ "org_name": { "description": "Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", "example": "Example Name", + "nullable": true, "type": "string" }, "org_slug": { "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.", "example": "example-slug", + "nullable": true, "type": "string" }, "owners": { @@ -104118,6 +114752,7 @@ "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "screenshot_urls": { @@ -104133,11 +114768,13 @@ "solution_id": { "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.", "example": "01234567-89ab-cdef-0123-456789abcdef", + "nullable": true, "type": "string" }, "solution_version": { "description": "Semver string declared in the Solution body (e.g. `\"1.2.0\"`). `null` when the body does not declare a version.", "example": "1.2.0", + "nullable": true, "type": "string" }, "tag_keys": { @@ -104153,6 +114790,7 @@ "template_kind": { "description": "Wrapped template kind — `\"AgentTemplate\"`, `\"AutomationTemplate\"`, `\"AgentRoutineTemplate\"`, `\"AgentToolTemplate\"`, `\"AgentComputerTemplate\"`, or `\"SolutionTemplateRef\"` for ref-mode bundles.", "example": "AgentTemplate", + "nullable": true, "type": "string" }, "templates": { @@ -104185,6 +114823,7 @@ "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "details": { @@ -104192,6 +114831,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -104216,12 +114856,13 @@ }, "properties": { "automation_type": { - "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`).", + "description": "Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", "example": "string", + "nullable": true, "type": "string" }, "invoke_contract": { - "description": "Schema-driven payload and participant inputs for an invoked automation. Used by installation clients to collect locked prefills before provisioning.", + "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.", "example": { "input_schema": {}, "participants": [ @@ -104237,10 +114878,12 @@ "payload": {} } }, + "nullable": true, "properties": { "input_schema": { "description": "JSON Schema validated against the whole invoke payload, from the automation's `input_schema_config`. `null` when none is configured.", "example": {}, + "nullable": true, "type": "object" }, "participants": { @@ -104261,10 +114904,12 @@ "required": true, "type": "agent_user" }, + "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", "example": "An example description.", + "nullable": true, "type": "string" }, "name": { @@ -104290,6 +114935,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -104338,11 +114984,13 @@ "display_name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "id": { "description": "Template config ID (`cfg_...`). `null` for inline-only templates.", "example": "id_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "kind": { @@ -104353,21 +115001,25 @@ "lookup_key": { "description": "Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", "example": "string", + "nullable": true, "type": "string" }, "name": { "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`.", "example": "Example Name", + "nullable": true, "type": "string" }, "readme_url": { "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`.", "example": "https://example.com", + "nullable": true, "type": "string" }, "virtual_path": { "description": "Stable virtual path assigned to the template config. `null` when no virtual path was set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -104380,8 +115032,7 @@ }, "updated_at": { "description": "When the Solution config was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "upgrade_available": { @@ -104392,6 +115043,7 @@ "virtual_path": { "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.", "example": "string", + "nullable": true, "type": "string" } }, @@ -104427,11 +115079,13 @@ "description": { "description": "Description of the template from the config body. `null` if the current version has no `description` field.", "example": "An example description.", + "nullable": true, "type": "string" }, "display_name": { "description": "Human-readable display name from the config body. `null` if the current version has no `display_name` field.", "example": "Example Name", + "nullable": true, "type": "string" }, "id": { @@ -104447,11 +115101,13 @@ "lookup_key": { "description": "Stable lookup key assigned to this template config. `null` if no lookup key is set.", "example": "string", + "nullable": true, "type": "string" }, "name": { "description": "Template name as stored in the config body. `null` if the current version has no `name` field.", "example": "Example Name", + "nullable": true, "type": "string" }, "updated_at": { @@ -104463,6 +115119,7 @@ "virtual_path": { "description": "Virtual filesystem path for this template config. `null` if not set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -104482,22 +115139,24 @@ "team": { "description": "ID of the team that owns this agent (`tem_...`). `null` if the agent is not team-scoped.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "template_upgrade_available": { "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`).", "example": true, + "nullable": true, "type": "boolean" }, "updated_at": { "description": "When the agent was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "user": { "description": "ID of the user that owns this agent (`usr_...`). `null` if the agent is not user-scoped.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" } }, @@ -104506,16 +115165,19 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "role": { "description": "The authenticated user's membership role in this thread, e.g. `\"owner\"`, `\"member\"`, or `\"viewer\"`. `null` if the user is not a member.", "example": "member", + "nullable": true, "type": "string" }, "sandbox": { "description": "ID of the developer sandbox this thread is scoped to (`dsb_...`). `null` for production threads.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "settings": { @@ -104525,8 +115187,9 @@ }, "properties": { "agent_enabled": { - "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.", + "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.", "example": true, + "nullable": true, "type": "boolean" } }, @@ -104535,6 +115198,7 @@ "slug": { "description": "URL-safe slug for the thread, used in human-readable permalinks. `null` if not assigned.", "example": "example-slug", + "nullable": true, "type": "string" }, "sub_threads": { @@ -104543,8 +115207,10 @@ {} ], "items": { + "nullable": true, "type": "object" }, + "nullable": true, "type": "array" }, "tags": { @@ -104561,32 +115227,36 @@ "team": { "description": "ID of the team that owns this thread (`team_...`). `null` for user-owned or agent-owned threads.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "title": { "description": "Human-readable name of the thread. `null` if no title has been set.", "example": "Example Title", + "nullable": true, "type": "string" }, "ttl": { - "description": "Time-to-live in seconds after which the thread may be automatically cleaned up. `null` if the thread does not expire.", - "example": 3600, - "type": "integer" + "description": "Offset-free expiry timestamp after which the thread may be automatically cleaned up. `null` if the thread does not expire.", + "example": "2026-08-15T12:00:00", + "nullable": true, + "type": "string" }, "unread_count": { "description": "Number of messages in this thread that the authenticated user has not yet read. Present only when read-state enrichment is requested.", "example": 5, + "nullable": true, "type": "integer" }, "updated_at": { "description": "When the thread was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "user": { "description": "ID of the user who owns this thread (`usr_...`). `null` for team-owned or agent-owned threads.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "visibility": { @@ -104798,7 +115468,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" } }, @@ -104938,7 +115608,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "properties": { @@ -104972,6 +115642,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -105153,16 +115824,19 @@ "alias": { "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", "example": "alice", + "nullable": true, "type": "string" }, "id": { "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "nullable": true, "type": "string" }, "name": { "description": "Display name of the actor shown in the UI. `null` if no name is set.", "example": "Example Name", + "nullable": true, "type": "string" }, "profile_picture": { @@ -105176,40 +115850,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -105223,6 +115905,7 @@ "agent": { "description": "ID of the agent user that sent this message (`agi_...`). `null` for messages sent by human users.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "agent_mode": { @@ -105232,6 +115915,7 @@ "embedded" ], "example": "cli", + "nullable": true, "type": "string" }, "attachments": { @@ -105344,21 +116028,25 @@ "content_type": { "description": "MIME type of the attached file, e.g. `\"image/png\"` or `\"application/pdf\"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.", "example": "application/json", + "nullable": true, "type": "string" }, "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "filename": { "description": "Original filename of the attached file, e.g. `\"report.pdf\"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.", "example": "string", + "nullable": true, "type": "string" }, "height": { "description": "Height in pixels of the media item. Present on `media` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "id": { @@ -105369,6 +116057,7 @@ "image_height": { "description": "Height in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "image_source": { @@ -105382,40 +116071,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -105424,31 +116121,35 @@ "image_url": { "description": "URL of the preview image extracted from the scraped page. Present on `scraped_link` type only. `null` otherwise.", "example": "https://example.com", + "nullable": true, "type": "string" }, "image_width": { "description": "Width in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "media_type": { - "description": "The media category, e.g. `\"video\"` or `\"audio\"`. Present on `media` type only. `null` otherwise.", + "description": "The media category, e.g. `\"video\"` or `\"audio\"`. Present on `media` type only; omitted otherwise.", "example": "application/json", "type": "string" }, "name": { "description": "Display name of the media item. Present on `media` type only. `null` otherwise.", "example": "Example Name", + "nullable": true, "type": "string" }, "object": { - "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`. `null` on other types.", + "description": "The full embedded object payload. For `task` type, contains the task record. For `action` type, contains the action definition. For `chart` type, contains the chart with its inline `spec`. Omitted on other types.", "example": {}, "type": "object" }, "title": { "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.", "example": "Example Title", + "nullable": true, "type": "string" }, "type": { @@ -105459,10 +116160,11 @@ "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "variants": { - "description": "Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only. `null` otherwise.", + "description": "Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only; omitted otherwise.", "example": [ { "content_type": "application/json", @@ -105513,6 +116215,7 @@ "content_type": { "description": "MIME type of this variant's file (e.g., `\"image/jpeg\"`, `\"video/mp4\"`). `null` if the file is not loaded.", "example": "application/json", + "nullable": true, "type": "string" }, "created_at": { @@ -105529,11 +116232,13 @@ "filename": { "description": "Original filename of the uploaded file for this variant. `null` if the file is not loaded.", "example": "string", + "nullable": true, "type": "string" }, "height": { "description": "Height of this variant in pixels. `null` if not recorded.", "example": 600, + "nullable": true, "type": "integer" }, "id": { @@ -105552,40 +116257,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -105600,6 +116313,7 @@ "url": { "description": "Signed download URL for this variant, resolved at request time. `null` if the file is unavailable.", "example": "https://example.com", + "nullable": true, "type": "string" }, "variant_key": { @@ -105610,6 +116324,7 @@ "width": { "description": "Width of this variant in pixels. `null` if not recorded.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -105623,11 +116338,13 @@ "version": { "description": "Version number of the attached artifact at the time of attachment. Present on `artifact` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "width": { "description": "Width in pixels of the media item. Present on `media` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" } }, @@ -105642,17 +116359,18 @@ "branched_thread": { "description": "ID of the thread that was branched from this message (`thr_...`). `null` if this message has not spawned a branch thread.", "example": "string", + "nullable": true, "type": "string" }, "content": { "description": "Text content of the message. `null` for messages that contain only attachments.", "example": "Hello, how can I help you today?", + "nullable": true, "type": "string" }, "created_at": { "description": "When the message was posted (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "has_replies": { @@ -105668,6 +116386,7 @@ "idempotency_key": { "description": "Client-supplied idempotency key used to deduplicate message sends. `null` if the sender did not provide one.", "example": "01234567-89ab-cdef-0123-456789abcdef", + "nullable": true, "type": "string" }, "is_deleted": { @@ -105678,6 +116397,7 @@ "legacy_agent": { "description": "Identifier of the legacy chat agent that sent this message, if applicable. `null` for messages sent by users or modern agent users.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -105690,6 +116410,7 @@ "org": { "description": "ID of the organization that owns this message (`org_...`).", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "reactions": { @@ -105741,6 +116462,7 @@ "rendering_mode": { "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.", "example": "reply", + "nullable": true, "type": "string" }, "replies": { @@ -105756,11 +116478,13 @@ "replies_after_cursor": { "description": "Opaque pagination cursor to fetch replies posted after the current page. Only present when inline replies are included in the response.", "example": "string", + "nullable": true, "type": "string" }, "replies_before_cursor": { "description": "Opaque pagination cursor to fetch replies posted before the current page. Only present when inline replies are included in the response.", "example": "string", + "nullable": true, "type": "string" }, "reply_count": { @@ -105903,9 +116627,10 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, + "nullable": true, "type": "object" }, "root_message_id": { @@ -105917,27 +116642,180 @@ "sandbox": { "description": "ID of the developer sandbox this message belongs to (`dsb_...`). `null` for non-sandbox messages.", "example": "string", + "nullable": true, "type": "string" }, "team": { "description": "ID of the team this message is scoped to (`tem_...`). `null` if the message is not team-scoped.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "thread": { - "description": "ID of the thread this message belongs to (`thr_...`). `null` for messages not yet associated with a thread.", + "description": "ID of the thread this message belongs to (`thr_...`).", "example": "string", "type": "string" }, "type": { "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.", "example": "note", + "nullable": true, "type": "string" }, "user": { "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.", - "example": "string", - "type": "string" + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "oneOf": [ + { + "type": "string" + }, + { + "description": "A platform user account. Represents a human or system actor that can own threads, belong to an organization, and interact with the API.", + "example": { + "alias": "jdoe", + "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "email": "user@example.com", + "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "is_system_user": true, + "metadata": { + "key": "value" + }, + "name": "Example Name", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "org_name": "Example Name", + "org_role": "member", + "org_slug": "example-slug", + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "sandbox_name": "Example Name" + }, + "properties": { + "alias": { + "description": "Short handle or alias for the user. `null` if not set.", + "example": "jdoe", + "nullable": true, + "type": "string" + }, + "app": { + "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.", + "example": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "app_name": { + "description": "Display name of the user's app. `null` when the app association was not preloaded by the caller.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "created_by_agent_user": { + "description": "Agent user that created this account (`usr_...`). `null` unless an agent created it.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_developer": { + "description": "Developer account that created this user (`dva_...`). `null` unless created via a developer token.", + "example": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_org": { + "description": "Org of the principal that created this user (`org_...`). `null` on legacy rows.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_team": { + "description": "Team that created this user (`tem_...`). `null` unless created as a team.", + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_user": { + "description": "User who created this account (`usr_...`). `null` on self-signup or legacy rows.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "email": { + "description": "Email address of the user.", + "example": "user@example.com", + "nullable": true, + "type": "string" + }, + "id": { + "description": "User ID (`usr_...`).", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "is_system_user": { + "description": "`true` if this account is an internal system user rather than a human. System users are created automatically by the platform.", + "example": true, + "type": "boolean" + }, + "metadata": { + "description": "Arbitrary key-value metadata attached to the user. Defaults to an empty object.", + "example": { + "key": "value" + }, + "type": "object" + }, + "name": { + "description": "Full display name of the user. `null` if the user has not set a name.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "org": { + "description": "ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "org_name": { + "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.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "org_role": { + "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.", + "example": "member", + "nullable": true, + "type": "string" + }, + "org_slug": { + "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.", + "example": "example-slug", + "nullable": true, + "type": "string" + }, + "sandbox": { + "description": "ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.", + "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "sandbox_name": { + "description": "Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.", + "example": "Example Name", + "nullable": true, + "type": "string" + } + }, + "required": [ + "id" + ], + "type": "object" + } + ] }, "visibility": { "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.", @@ -106122,7 +117000,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" } }, @@ -106262,7 +117140,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "properties": { @@ -106296,6 +117174,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -106477,16 +117356,19 @@ "alias": { "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", "example": "alice", + "nullable": true, "type": "string" }, "id": { "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "nullable": true, "type": "string" }, "name": { "description": "Display name of the actor shown in the UI. `null` if no name is set.", "example": "Example Name", + "nullable": true, "type": "string" }, "profile_picture": { @@ -106500,40 +117382,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -106547,6 +117437,7 @@ "agent": { "description": "ID of the agent user that sent this message (`agi_...`). `null` for messages sent by human users.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "agent_mode": { @@ -106556,6 +117447,7 @@ "embedded" ], "example": "cli", + "nullable": true, "type": "string" }, "attachments": { @@ -106668,21 +117560,25 @@ "content_type": { "description": "MIME type of the attached file, e.g. `\"image/png\"` or `\"application/pdf\"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.", "example": "application/json", + "nullable": true, "type": "string" }, "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "filename": { "description": "Original filename of the attached file, e.g. `\"report.pdf\"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.", "example": "string", + "nullable": true, "type": "string" }, "height": { "description": "Height in pixels of the media item. Present on `media` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "id": { @@ -106693,6 +117589,7 @@ "image_height": { "description": "Height in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "image_source": { @@ -106706,40 +117603,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -106748,31 +117653,35 @@ "image_url": { "description": "URL of the preview image extracted from the scraped page. Present on `scraped_link` type only. `null` otherwise.", "example": "https://example.com", + "nullable": true, "type": "string" }, "image_width": { "description": "Width in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "media_type": { - "description": "The media category, e.g. `\"video\"` or `\"audio\"`. Present on `media` type only. `null` otherwise.", + "description": "The media category, e.g. `\"video\"` or `\"audio\"`. Present on `media` type only; omitted otherwise.", "example": "application/json", "type": "string" }, "name": { "description": "Display name of the media item. Present on `media` type only. `null` otherwise.", "example": "Example Name", + "nullable": true, "type": "string" }, "object": { - "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`. `null` on other types.", + "description": "The full embedded object payload. For `task` type, contains the task record. For `action` type, contains the action definition. For `chart` type, contains the chart with its inline `spec`. Omitted on other types.", "example": {}, "type": "object" }, "title": { "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.", "example": "Example Title", + "nullable": true, "type": "string" }, "type": { @@ -106783,10 +117692,11 @@ "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "variants": { - "description": "Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only. `null` otherwise.", + "description": "Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only; omitted otherwise.", "example": [ { "content_type": "application/json", @@ -106837,6 +117747,7 @@ "content_type": { "description": "MIME type of this variant's file (e.g., `\"image/jpeg\"`, `\"video/mp4\"`). `null` if the file is not loaded.", "example": "application/json", + "nullable": true, "type": "string" }, "created_at": { @@ -106853,11 +117764,13 @@ "filename": { "description": "Original filename of the uploaded file for this variant. `null` if the file is not loaded.", "example": "string", + "nullable": true, "type": "string" }, "height": { "description": "Height of this variant in pixels. `null` if not recorded.", "example": 600, + "nullable": true, "type": "integer" }, "id": { @@ -106876,40 +117789,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -106924,6 +117845,7 @@ "url": { "description": "Signed download URL for this variant, resolved at request time. `null` if the file is unavailable.", "example": "https://example.com", + "nullable": true, "type": "string" }, "variant_key": { @@ -106934,6 +117856,7 @@ "width": { "description": "Width of this variant in pixels. `null` if not recorded.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -106947,11 +117870,13 @@ "version": { "description": "Version number of the attached artifact at the time of attachment. Present on `artifact` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "width": { "description": "Width in pixels of the media item. Present on `media` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" } }, @@ -106966,17 +117891,18 @@ "branched_thread": { "description": "ID of the thread that was branched from this message (`thr_...`). `null` if this message has not spawned a branch thread.", "example": "string", + "nullable": true, "type": "string" }, "content": { "description": "Text content of the message. `null` for messages that contain only attachments.", "example": "Hello, how can I help you today?", + "nullable": true, "type": "string" }, "created_at": { "description": "When the message was posted (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "has_replies": { @@ -106992,6 +117918,7 @@ "idempotency_key": { "description": "Client-supplied idempotency key used to deduplicate message sends. `null` if the sender did not provide one.", "example": "01234567-89ab-cdef-0123-456789abcdef", + "nullable": true, "type": "string" }, "is_deleted": { @@ -107002,6 +117929,7 @@ "legacy_agent": { "description": "Identifier of the legacy chat agent that sent this message, if applicable. `null` for messages sent by users or modern agent users.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -107014,6 +117942,7 @@ "org": { "description": "ID of the organization that owns this message (`org_...`).", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "reactions": { @@ -107065,6 +117994,7 @@ "rendering_mode": { "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.", "example": "reply", + "nullable": true, "type": "string" }, "replies": { @@ -107080,11 +118010,13 @@ "replies_after_cursor": { "description": "Opaque pagination cursor to fetch replies posted after the current page. Only present when inline replies are included in the response.", "example": "string", + "nullable": true, "type": "string" }, "replies_before_cursor": { "description": "Opaque pagination cursor to fetch replies posted before the current page. Only present when inline replies are included in the response.", "example": "string", + "nullable": true, "type": "string" }, "reply_count": { @@ -107227,9 +118159,10 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, + "nullable": true, "type": "object" }, "root_message_id": { @@ -107241,27 +118174,180 @@ "sandbox": { "description": "ID of the developer sandbox this message belongs to (`dsb_...`). `null` for non-sandbox messages.", "example": "string", + "nullable": true, "type": "string" }, "team": { "description": "ID of the team this message is scoped to (`tem_...`). `null` if the message is not team-scoped.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "thread": { - "description": "ID of the thread this message belongs to (`thr_...`). `null` for messages not yet associated with a thread.", + "description": "ID of the thread this message belongs to (`thr_...`).", "example": "string", "type": "string" }, "type": { "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.", "example": "note", + "nullable": true, "type": "string" }, "user": { "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.", - "example": "string", - "type": "string" + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "oneOf": [ + { + "type": "string" + }, + { + "description": "A platform user account. Represents a human or system actor that can own threads, belong to an organization, and interact with the API.", + "example": { + "alias": "jdoe", + "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "email": "user@example.com", + "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "is_system_user": true, + "metadata": { + "key": "value" + }, + "name": "Example Name", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "org_name": "Example Name", + "org_role": "member", + "org_slug": "example-slug", + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "sandbox_name": "Example Name" + }, + "properties": { + "alias": { + "description": "Short handle or alias for the user. `null` if not set.", + "example": "jdoe", + "nullable": true, + "type": "string" + }, + "app": { + "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.", + "example": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "app_name": { + "description": "Display name of the user's app. `null` when the app association was not preloaded by the caller.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "created_by_agent_user": { + "description": "Agent user that created this account (`usr_...`). `null` unless an agent created it.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_developer": { + "description": "Developer account that created this user (`dva_...`). `null` unless created via a developer token.", + "example": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_org": { + "description": "Org of the principal that created this user (`org_...`). `null` on legacy rows.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_team": { + "description": "Team that created this user (`tem_...`). `null` unless created as a team.", + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_user": { + "description": "User who created this account (`usr_...`). `null` on self-signup or legacy rows.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "email": { + "description": "Email address of the user.", + "example": "user@example.com", + "nullable": true, + "type": "string" + }, + "id": { + "description": "User ID (`usr_...`).", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "is_system_user": { + "description": "`true` if this account is an internal system user rather than a human. System users are created automatically by the platform.", + "example": true, + "type": "boolean" + }, + "metadata": { + "description": "Arbitrary key-value metadata attached to the user. Defaults to an empty object.", + "example": { + "key": "value" + }, + "type": "object" + }, + "name": { + "description": "Full display name of the user. `null` if the user has not set a name.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "org": { + "description": "ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "org_name": { + "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.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "org_role": { + "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.", + "example": "member", + "nullable": true, + "type": "string" + }, + "org_slug": { + "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.", + "example": "example-slug", + "nullable": true, + "type": "string" + }, + "sandbox": { + "description": "ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.", + "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "sandbox_name": { + "description": "Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.", + "example": "Example Name", + "nullable": true, + "type": "string" + } + }, + "required": [ + "id" + ], + "type": "object" + } + ] }, "visibility": { "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.", @@ -107566,7 +118652,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "thread_id": "string" @@ -107715,7 +118801,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "properties": { @@ -107749,6 +118835,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -107930,16 +119017,19 @@ "alias": { "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", "example": "alice", + "nullable": true, "type": "string" }, "id": { "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "nullable": true, "type": "string" }, "name": { "description": "Display name of the actor shown in the UI. `null` if no name is set.", "example": "Example Name", + "nullable": true, "type": "string" }, "profile_picture": { @@ -107953,40 +119043,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -108000,6 +119098,7 @@ "agent": { "description": "ID of the agent user that sent this message (`agi_...`). `null` for messages sent by human users.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "agent_mode": { @@ -108009,6 +119108,7 @@ "embedded" ], "example": "cli", + "nullable": true, "type": "string" }, "attachments": { @@ -108121,21 +119221,25 @@ "content_type": { "description": "MIME type of the attached file, e.g. `\"image/png\"` or `\"application/pdf\"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.", "example": "application/json", + "nullable": true, "type": "string" }, "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "filename": { "description": "Original filename of the attached file, e.g. `\"report.pdf\"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.", "example": "string", + "nullable": true, "type": "string" }, "height": { "description": "Height in pixels of the media item. Present on `media` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "id": { @@ -108146,6 +119250,7 @@ "image_height": { "description": "Height in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "image_source": { @@ -108159,40 +119264,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -108201,31 +119314,35 @@ "image_url": { "description": "URL of the preview image extracted from the scraped page. Present on `scraped_link` type only. `null` otherwise.", "example": "https://example.com", + "nullable": true, "type": "string" }, "image_width": { "description": "Width in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "media_type": { - "description": "The media category, e.g. `\"video\"` or `\"audio\"`. Present on `media` type only. `null` otherwise.", + "description": "The media category, e.g. `\"video\"` or `\"audio\"`. Present on `media` type only; omitted otherwise.", "example": "application/json", "type": "string" }, "name": { "description": "Display name of the media item. Present on `media` type only. `null` otherwise.", "example": "Example Name", + "nullable": true, "type": "string" }, "object": { - "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`. `null` on other types.", + "description": "The full embedded object payload. For `task` type, contains the task record. For `action` type, contains the action definition. For `chart` type, contains the chart with its inline `spec`. Omitted on other types.", "example": {}, "type": "object" }, "title": { "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.", "example": "Example Title", + "nullable": true, "type": "string" }, "type": { @@ -108236,10 +119353,11 @@ "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "variants": { - "description": "Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only. `null` otherwise.", + "description": "Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only; omitted otherwise.", "example": [ { "content_type": "application/json", @@ -108290,6 +119408,7 @@ "content_type": { "description": "MIME type of this variant's file (e.g., `\"image/jpeg\"`, `\"video/mp4\"`). `null` if the file is not loaded.", "example": "application/json", + "nullable": true, "type": "string" }, "created_at": { @@ -108306,11 +119425,13 @@ "filename": { "description": "Original filename of the uploaded file for this variant. `null` if the file is not loaded.", "example": "string", + "nullable": true, "type": "string" }, "height": { "description": "Height of this variant in pixels. `null` if not recorded.", "example": 600, + "nullable": true, "type": "integer" }, "id": { @@ -108329,40 +119450,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -108377,6 +119506,7 @@ "url": { "description": "Signed download URL for this variant, resolved at request time. `null` if the file is unavailable.", "example": "https://example.com", + "nullable": true, "type": "string" }, "variant_key": { @@ -108387,6 +119517,7 @@ "width": { "description": "Width of this variant in pixels. `null` if not recorded.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -108400,11 +119531,13 @@ "version": { "description": "Version number of the attached artifact at the time of attachment. Present on `artifact` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "width": { "description": "Width in pixels of the media item. Present on `media` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" } }, @@ -108419,17 +119552,18 @@ "branched_thread": { "description": "ID of the thread that was branched from this message (`thr_...`). `null` if this message has not spawned a branch thread.", "example": "string", + "nullable": true, "type": "string" }, "content": { "description": "Text content of the message. `null` for messages that contain only attachments.", "example": "Hello, how can I help you today?", + "nullable": true, "type": "string" }, "created_at": { "description": "When the message was posted (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "has_replies": { @@ -108445,6 +119579,7 @@ "idempotency_key": { "description": "Client-supplied idempotency key used to deduplicate message sends. `null` if the sender did not provide one.", "example": "01234567-89ab-cdef-0123-456789abcdef", + "nullable": true, "type": "string" }, "is_deleted": { @@ -108455,6 +119590,7 @@ "legacy_agent": { "description": "Identifier of the legacy chat agent that sent this message, if applicable. `null` for messages sent by users or modern agent users.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -108467,6 +119603,7 @@ "org": { "description": "ID of the organization that owns this message (`org_...`).", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "reactions": { @@ -108518,6 +119655,7 @@ "rendering_mode": { "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.", "example": "reply", + "nullable": true, "type": "string" }, "replies": { @@ -108533,11 +119671,13 @@ "replies_after_cursor": { "description": "Opaque pagination cursor to fetch replies posted after the current page. Only present when inline replies are included in the response.", "example": "string", + "nullable": true, "type": "string" }, "replies_before_cursor": { "description": "Opaque pagination cursor to fetch replies posted before the current page. Only present when inline replies are included in the response.", "example": "string", + "nullable": true, "type": "string" }, "reply_count": { @@ -108680,9 +119820,10 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, + "nullable": true, "type": "object" }, "root_message_id": { @@ -108694,27 +119835,180 @@ "sandbox": { "description": "ID of the developer sandbox this message belongs to (`dsb_...`). `null` for non-sandbox messages.", "example": "string", + "nullable": true, "type": "string" }, "team": { "description": "ID of the team this message is scoped to (`tem_...`). `null` if the message is not team-scoped.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "thread": { - "description": "ID of the thread this message belongs to (`thr_...`). `null` for messages not yet associated with a thread.", + "description": "ID of the thread this message belongs to (`thr_...`).", "example": "string", "type": "string" }, "type": { "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.", "example": "note", + "nullable": true, "type": "string" }, "user": { "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.", - "example": "string", - "type": "string" + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "oneOf": [ + { + "type": "string" + }, + { + "description": "A platform user account. Represents a human or system actor that can own threads, belong to an organization, and interact with the API.", + "example": { + "alias": "jdoe", + "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "email": "user@example.com", + "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "is_system_user": true, + "metadata": { + "key": "value" + }, + "name": "Example Name", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "org_name": "Example Name", + "org_role": "member", + "org_slug": "example-slug", + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "sandbox_name": "Example Name" + }, + "properties": { + "alias": { + "description": "Short handle or alias for the user. `null` if not set.", + "example": "jdoe", + "nullable": true, + "type": "string" + }, + "app": { + "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.", + "example": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "app_name": { + "description": "Display name of the user's app. `null` when the app association was not preloaded by the caller.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "created_by_agent_user": { + "description": "Agent user that created this account (`usr_...`). `null` unless an agent created it.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_developer": { + "description": "Developer account that created this user (`dva_...`). `null` unless created via a developer token.", + "example": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_org": { + "description": "Org of the principal that created this user (`org_...`). `null` on legacy rows.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_team": { + "description": "Team that created this user (`tem_...`). `null` unless created as a team.", + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_user": { + "description": "User who created this account (`usr_...`). `null` on self-signup or legacy rows.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "email": { + "description": "Email address of the user.", + "example": "user@example.com", + "nullable": true, + "type": "string" + }, + "id": { + "description": "User ID (`usr_...`).", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "is_system_user": { + "description": "`true` if this account is an internal system user rather than a human. System users are created automatically by the platform.", + "example": true, + "type": "boolean" + }, + "metadata": { + "description": "Arbitrary key-value metadata attached to the user. Defaults to an empty object.", + "example": { + "key": "value" + }, + "type": "object" + }, + "name": { + "description": "Full display name of the user. `null` if the user has not set a name.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "org": { + "description": "ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "org_name": { + "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.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "org_role": { + "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.", + "example": "member", + "nullable": true, + "type": "string" + }, + "org_slug": { + "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.", + "example": "example-slug", + "nullable": true, + "type": "string" + }, + "sandbox": { + "description": "ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.", + "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "sandbox_name": { + "description": "Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.", + "example": "Example Name", + "nullable": true, + "type": "string" + } + }, + "required": [ + "id" + ], + "type": "object" + } + ] }, "visibility": { "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.", @@ -108877,7 +120171,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "thread_id": "string" @@ -109018,7 +120312,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "properties": { @@ -109052,6 +120346,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -109233,16 +120528,19 @@ "alias": { "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", "example": "alice", + "nullable": true, "type": "string" }, "id": { "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "nullable": true, "type": "string" }, "name": { "description": "Display name of the actor shown in the UI. `null` if no name is set.", "example": "Example Name", + "nullable": true, "type": "string" }, "profile_picture": { @@ -109256,40 +120554,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -109303,6 +120609,7 @@ "agent": { "description": "ID of the agent user that sent this message (`agi_...`). `null` for messages sent by human users.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "agent_mode": { @@ -109312,6 +120619,7 @@ "embedded" ], "example": "cli", + "nullable": true, "type": "string" }, "attachments": { @@ -109424,21 +120732,25 @@ "content_type": { "description": "MIME type of the attached file, e.g. `\"image/png\"` or `\"application/pdf\"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.", "example": "application/json", + "nullable": true, "type": "string" }, "description": { "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.", "example": "An example description.", + "nullable": true, "type": "string" }, "filename": { "description": "Original filename of the attached file, e.g. `\"report.pdf\"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.", "example": "string", + "nullable": true, "type": "string" }, "height": { "description": "Height in pixels of the media item. Present on `media` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "id": { @@ -109449,6 +120761,7 @@ "image_height": { "description": "Height in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "image_source": { @@ -109462,40 +120775,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -109504,31 +120825,35 @@ "image_url": { "description": "URL of the preview image extracted from the scraped page. Present on `scraped_link` type only. `null` otherwise.", "example": "https://example.com", + "nullable": true, "type": "string" }, "image_width": { "description": "Width in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "media_type": { - "description": "The media category, e.g. `\"video\"` or `\"audio\"`. Present on `media` type only. `null` otherwise.", + "description": "The media category, e.g. `\"video\"` or `\"audio\"`. Present on `media` type only; omitted otherwise.", "example": "application/json", "type": "string" }, "name": { "description": "Display name of the media item. Present on `media` type only. `null` otherwise.", "example": "Example Name", + "nullable": true, "type": "string" }, "object": { - "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`. `null` on other types.", + "description": "The full embedded object payload. For `task` type, contains the task record. For `action` type, contains the action definition. For `chart` type, contains the chart with its inline `spec`. Omitted on other types.", "example": {}, "type": "object" }, "title": { "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.", "example": "Example Title", + "nullable": true, "type": "string" }, "type": { @@ -109539,10 +120864,11 @@ "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "variants": { - "description": "Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only. `null` otherwise.", + "description": "Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only; omitted otherwise.", "example": [ { "content_type": "application/json", @@ -109593,6 +120919,7 @@ "content_type": { "description": "MIME type of this variant's file (e.g., `\"image/jpeg\"`, `\"video/mp4\"`). `null` if the file is not loaded.", "example": "application/json", + "nullable": true, "type": "string" }, "created_at": { @@ -109609,11 +120936,13 @@ "filename": { "description": "Original filename of the uploaded file for this variant. `null` if the file is not loaded.", "example": "string", + "nullable": true, "type": "string" }, "height": { "description": "Height of this variant in pixels. `null` if not recorded.", "example": 600, + "nullable": true, "type": "integer" }, "id": { @@ -109632,40 +120961,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -109680,6 +121017,7 @@ "url": { "description": "Signed download URL for this variant, resolved at request time. `null` if the file is unavailable.", "example": "https://example.com", + "nullable": true, "type": "string" }, "variant_key": { @@ -109690,6 +121028,7 @@ "width": { "description": "Width of this variant in pixels. `null` if not recorded.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -109703,11 +121042,13 @@ "version": { "description": "Version number of the attached artifact at the time of attachment. Present on `artifact` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" }, "width": { "description": "Width in pixels of the media item. Present on `media` type only. `null` otherwise.", "example": 1, + "nullable": true, "type": "integer" } }, @@ -109722,17 +121063,18 @@ "branched_thread": { "description": "ID of the thread that was branched from this message (`thr_...`). `null` if this message has not spawned a branch thread.", "example": "string", + "nullable": true, "type": "string" }, "content": { "description": "Text content of the message. `null` for messages that contain only attachments.", "example": "Hello, how can I help you today?", + "nullable": true, "type": "string" }, "created_at": { "description": "When the message was posted (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "example": "string", "type": "string" }, "has_replies": { @@ -109748,6 +121090,7 @@ "idempotency_key": { "description": "Client-supplied idempotency key used to deduplicate message sends. `null` if the sender did not provide one.", "example": "01234567-89ab-cdef-0123-456789abcdef", + "nullable": true, "type": "string" }, "is_deleted": { @@ -109758,6 +121101,7 @@ "legacy_agent": { "description": "Identifier of the legacy chat agent that sent this message, if applicable. `null` for messages sent by users or modern agent users.", "example": "string", + "nullable": true, "type": "string" }, "metadata": { @@ -109770,6 +121114,7 @@ "org": { "description": "ID of the organization that owns this message (`org_...`).", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "reactions": { @@ -109821,6 +121166,7 @@ "rendering_mode": { "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.", "example": "reply", + "nullable": true, "type": "string" }, "replies": { @@ -109836,11 +121182,13 @@ "replies_after_cursor": { "description": "Opaque pagination cursor to fetch replies posted after the current page. Only present when inline replies are included in the response.", "example": "string", + "nullable": true, "type": "string" }, "replies_before_cursor": { "description": "Opaque pagination cursor to fetch replies posted before the current page. Only present when inline replies are included in the response.", "example": "string", + "nullable": true, "type": "string" }, "reply_count": { @@ -109983,9 +121331,10 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, + "nullable": true, "type": "object" }, "root_message_id": { @@ -109997,27 +121346,180 @@ "sandbox": { "description": "ID of the developer sandbox this message belongs to (`dsb_...`). `null` for non-sandbox messages.", "example": "string", + "nullable": true, "type": "string" }, "team": { "description": "ID of the team this message is scoped to (`tem_...`). `null` if the message is not team-scoped.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "thread": { - "description": "ID of the thread this message belongs to (`thr_...`). `null` for messages not yet associated with a thread.", + "description": "ID of the thread this message belongs to (`thr_...`).", "example": "string", "type": "string" }, "type": { "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.", "example": "note", + "nullable": true, "type": "string" }, "user": { "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.", - "example": "string", - "type": "string" + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "oneOf": [ + { + "type": "string" + }, + { + "description": "A platform user account. Represents a human or system actor that can own threads, belong to an organization, and interact with the API.", + "example": { + "alias": "jdoe", + "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "app_name": "Example Name", + "created_by_agent_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_developer": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "created_by_user": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "email": "user@example.com", + "id": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "is_system_user": true, + "metadata": { + "key": "value" + }, + "name": "Example Name", + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "org_name": "Example Name", + "org_role": "member", + "org_slug": "example-slug", + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "sandbox_name": "Example Name" + }, + "properties": { + "alias": { + "description": "Short handle or alias for the user. `null` if not set.", + "example": "jdoe", + "nullable": true, + "type": "string" + }, + "app": { + "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.", + "example": "dap_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "app_name": { + "description": "Display name of the user's app. `null` when the app association was not preloaded by the caller.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "created_by_agent_user": { + "description": "Agent user that created this account (`usr_...`). `null` unless an agent created it.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_developer": { + "description": "Developer account that created this user (`dva_...`). `null` unless created via a developer token.", + "example": "dva_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_org": { + "description": "Org of the principal that created this user (`org_...`). `null` on legacy rows.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_team": { + "description": "Team that created this user (`tem_...`). `null` unless created as a team.", + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "created_by_user": { + "description": "User who created this account (`usr_...`). `null` on self-signup or legacy rows.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "email": { + "description": "Email address of the user.", + "example": "user@example.com", + "nullable": true, + "type": "string" + }, + "id": { + "description": "User ID (`usr_...`).", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "is_system_user": { + "description": "`true` if this account is an internal system user rather than a human. System users are created automatically by the platform.", + "example": true, + "type": "boolean" + }, + "metadata": { + "description": "Arbitrary key-value metadata attached to the user. Defaults to an empty object.", + "example": { + "key": "value" + }, + "type": "object" + }, + "name": { + "description": "Full display name of the user. `null` if the user has not set a name.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "org": { + "description": "ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "org_name": { + "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.", + "example": "Example Name", + "nullable": true, + "type": "string" + }, + "org_role": { + "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.", + "example": "member", + "nullable": true, + "type": "string" + }, + "org_slug": { + "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.", + "example": "example-slug", + "nullable": true, + "type": "string" + }, + "sandbox": { + "description": "ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.", + "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "sandbox_name": { + "description": "Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.", + "example": "Example Name", + "nullable": true, + "type": "string" + } + }, + "required": [ + "id" + ], + "type": "object" + } + ] }, "visibility": { "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.", @@ -110127,16 +121629,19 @@ "alias": { "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", "example": "alice", + "nullable": true, "type": "string" }, "id": { "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "nullable": true, "type": "string" }, "name": { "description": "Display name of the actor shown in the UI. `null` if no name is set.", "example": "Example Name", + "nullable": true, "type": "string" }, "profile_picture": { @@ -110150,40 +121655,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -110744,6 +122257,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -110773,6 +122287,9 @@ "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "priority": 2, "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", "status": "open", "subtasks_count": 1, "tags": [ @@ -110817,6 +122334,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -110846,6 +122364,9 @@ "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "priority": 2, "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", "status": "open", "subtasks_count": 1, "tags": [ @@ -110888,6 +122409,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -110917,6 +122439,9 @@ "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "priority": 2, "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", "status": "open", "subtasks_count": 1, "tags": [ @@ -110931,6 +122456,7 @@ "agent": { "description": "ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "blocked_by_count": { @@ -110942,6 +122468,7 @@ "description": "When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", "example": "2024-01-01T00:00:00Z", "format": "date-time", + "nullable": true, "type": "string" }, "comments_count": { @@ -110971,20 +122498,24 @@ "width": 800 } }, + "nullable": true, "properties": { "alias": { "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", "example": "alice", + "nullable": true, "type": "string" }, "id": { "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "nullable": true, "type": "string" }, "name": { "description": "Display name of the actor shown in the UI. `null` if no name is set.", "example": "Example Name", + "nullable": true, "type": "string" }, "profile_picture": { @@ -110998,40 +122529,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -111043,11 +122582,13 @@ "created_by_agent": { "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.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "created_by_user": { "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.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "current_lease": { @@ -111086,12 +122627,20 @@ "description": { "description": "Long-form description or notes for the task. `null` if no description has been provided.", "example": "An example description.", + "nullable": true, "type": "string" }, "due_date": { "description": "Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", "example": "2024-01-01T00:00:00Z", "format": "date-time", + "nullable": true, + "type": "string" + }, + "epic": { + "description": "Free-form grouping label. `null` when the task is not in an epic.", + "example": "string", + "nullable": true, "type": "string" }, "id": { @@ -111126,6 +122675,7 @@ "org": { "description": "ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "owner_actor": { @@ -111144,20 +122694,24 @@ "width": 800 } }, + "nullable": true, "properties": { "alias": { "description": "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", "example": "alice", + "nullable": true, "type": "string" }, "id": { "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", + "nullable": true, "type": "string" }, "name": { "description": "Display name of the actor shown in the UI. `null` if no name is set.", "example": "Example Name", + "nullable": true, "type": "string" }, "profile_picture": { @@ -111171,40 +122725,48 @@ "url": "https://example.com", "width": 800 }, + "nullable": true, "properties": { "file": { "description": "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "height": { "description": "Height of the image in pixels. `null` if not known.", "example": 600, + "nullable": true, "type": "integer" }, "media": { "description": "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", "example": "med_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "mime_type": { "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", "example": "application/json", + "nullable": true, "type": "string" }, "refresh_url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "url": { "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.", "example": "https://example.com", + "nullable": true, "type": "string" }, "width": { "description": "Width of the image in pixels. `null` if not known.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -111216,16 +122778,19 @@ "owner_agent": { "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.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "owner_user": { "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.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "parent": { "description": "ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks. Subtasks nest exactly one level.", "example": "tsk_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "priority": { @@ -111236,6 +122801,25 @@ "sandbox": { "description": "ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, + "type": "string" + }, + "source_id": { + "description": "Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", + "example": "string", + "nullable": true, + "type": "string" + }, + "source_scope": { + "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`.", + "example": "string", + "nullable": true, + "type": "string" + }, + "source_type": { + "description": "Kind of source object (for example `repository`). `null` when the task has no source.", + "example": "string", + "nullable": true, "type": "string" }, "status": { @@ -111261,11 +122845,13 @@ "team": { "description": "ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "thread": { "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.", "example": "thr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "updated_at": { @@ -111277,6 +122863,7 @@ "user": { "description": "ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" } }, diff --git a/src/archastro/platform/auth.py b/src/archastro/platform/auth.py index d5019bb..6b8de83 100644 --- a/src/archastro/platform/auth.py +++ b/src/archastro/platform/auth.py @@ -1,6 +1,6 @@ # Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. # This file is auto-generated by @archastro/sdk-generator. Do not edit. -# Content hash: 21861652201d +# Content hash: 753c8a0332f7 from __future__ import annotations @@ -146,6 +146,7 @@ async def register( full_name: str | None = None, invite_code: str | None = None, password: str | None = None, + set_org: str | None = None, team_invite: str | None = None, timezone: str | None = None, ) -> AuthTokens: @@ -168,6 +169,7 @@ async def register( full_name: Full name for the new account. invite_code: Invite code for invite-gated registration. Applied only in the standard registration path. password: Password for the new account. Required for standard (non-team-invite) registration. + set_org: Create or reuse an organization from the work-email domain and stamp the new user into it. team_invite: Team invite ID. When provided, the user is added to the team on registration. timezone: IANA timezone name for the new account, e.g. `"America/New_York"`. @@ -184,6 +186,8 @@ async def register( body["invite_code"] = invite_code if password is not None: body["password"] = password + if set_org is not None: + body["set_org"] = set_org if team_invite is not None: body["team_invite"] = team_invite if timezone is not None: @@ -206,6 +210,7 @@ async def request_register_magic_link( email: str | None = None, full_name: str | None = None, redirect_uri: str | None = None, + set_org: str | None = None, timezone: str | None = None, ) -> dict: """ @@ -224,6 +229,7 @@ async def request_register_magic_link( email: Email address to send the registration magic link to. full_name: Full name for the new account. redirect_uri: URL the user is redirected to after clicking the registration link. The token is appended as a query parameter. + set_org: Create or reuse an organization from the work-email domain during confirmation. timezone: IANA timezone name for the new account, e.g. `"America/New_York"`. Returns: @@ -238,6 +244,8 @@ async def request_register_magic_link( body["full_name"] = full_name if redirect_uri is not None: body["redirect_uri"] = redirect_uri + if set_org is not None: + body["set_org"] = set_org if timezone is not None: body["timezone"] = timezone @@ -249,7 +257,7 @@ async def request_register_magic_link( return data async def request_magic_link( - self, email: str | None = None, redirect_uri: str | None = None + self, email: str | None = None, redirect_uri: str | None = None, set_org: str | None = None ) -> dict: """ Request a magic link for login or registration @@ -265,6 +273,7 @@ async def request_magic_link( Args: email: Email address to send the magic link to. redirect_uri: URL the user is redirected to after clicking the magic link. Must be registered with the app. + set_org: For a new user, create or reuse an organization from the work-email domain during confirmation. Returns: No content @@ -274,6 +283,8 @@ async def request_magic_link( body["email"] = email if redirect_uri is not None: body["redirect_uri"] = redirect_uri + if set_org is not None: + body["set_org"] = set_org data = await self._http.request( "/api/v1/auth/request/link", @@ -482,6 +493,7 @@ def register( full_name: str | None = None, invite_code: str | None = None, password: str | None = None, + set_org: str | None = None, team_invite: str | None = None, timezone: str | None = None, ) -> AuthTokens: @@ -504,6 +516,7 @@ def register( full_name: Full name for the new account. invite_code: Invite code for invite-gated registration. Applied only in the standard registration path. password: Password for the new account. Required for standard (non-team-invite) registration. + set_org: Create or reuse an organization from the work-email domain and stamp the new user into it. team_invite: Team invite ID. When provided, the user is added to the team on registration. timezone: IANA timezone name for the new account, e.g. `"America/New_York"`. @@ -520,6 +533,8 @@ def register( body["invite_code"] = invite_code if password is not None: body["password"] = password + if set_org is not None: + body["set_org"] = set_org if team_invite is not None: body["team_invite"] = team_invite if timezone is not None: @@ -542,6 +557,7 @@ def request_register_magic_link( email: str | None = None, full_name: str | None = None, redirect_uri: str | None = None, + set_org: str | None = None, timezone: str | None = None, ) -> dict: """ @@ -560,6 +576,7 @@ def request_register_magic_link( email: Email address to send the registration magic link to. full_name: Full name for the new account. redirect_uri: URL the user is redirected to after clicking the registration link. The token is appended as a query parameter. + set_org: Create or reuse an organization from the work-email domain during confirmation. timezone: IANA timezone name for the new account, e.g. `"America/New_York"`. Returns: @@ -574,6 +591,8 @@ def request_register_magic_link( body["full_name"] = full_name if redirect_uri is not None: body["redirect_uri"] = redirect_uri + if set_org is not None: + body["set_org"] = set_org if timezone is not None: body["timezone"] = timezone @@ -584,7 +603,9 @@ def request_register_magic_link( ) return data - def request_magic_link(self, email: str | None = None, redirect_uri: str | None = None) -> dict: + def request_magic_link( + self, email: str | None = None, redirect_uri: str | None = None, set_org: str | None = None + ) -> dict: """ Request a magic link for login or registration Sends a passwordless magic link to the given email address. If an account with that @@ -599,6 +620,7 @@ def request_magic_link(self, email: str | None = None, redirect_uri: str | None Args: email: Email address to send the magic link to. redirect_uri: URL the user is redirected to after clicking the magic link. Must be registered with the app. + set_org: For a new user, create or reuse an organization from the work-email domain during confirmation. Returns: No content @@ -608,6 +630,8 @@ def request_magic_link(self, email: str | None = None, redirect_uri: str | None body["email"] = email if redirect_uri is not None: body["redirect_uri"] = redirect_uri + if set_org is not None: + body["set_org"] = set_org data = self._http.request( "/api/v1/auth/request/link", diff --git a/src/archastro/platform/channels/api_chat_channel.py b/src/archastro/platform/channels/api_chat_channel.py index dd8272f..4eedce6 100644 --- a/src/archastro/platform/channels/api_chat_channel.py +++ b/src/archastro/platform/channels/api_chat_channel.py @@ -1,6 +1,6 @@ # Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. # This file is auto-generated by @archastro/sdk-generator. Do not edit. -# Content hash: 47683c10bd61 +# Content hash: 81654b87b94d from collections.abc import Callable from datetime import datetime @@ -223,11 +223,11 @@ class MessageAddedPayloadMessageAttachmentsItem(TypedDict, total=False): image_width: int | None "Width in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise." media_type: str | None - 'The media category, e.g. `"video"` or `"audio"`. Present on `media` type only. `null` otherwise.' + 'The media category, e.g. `"video"` or `"audio"`. Present on `media` type only; omitted otherwise.' name: str | None "Display name of the media item. Present on `media` type only. `null` otherwise." object: dict[str, Any] | 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`. `null` on other types." + "The full embedded object payload. For `task` type, contains the task record. For `action` type, contains the action definition. For `chart` type, contains the chart with its inline `spec`. Omitted on other types." title: str | None "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: Required[str] @@ -235,7 +235,7 @@ class MessageAddedPayloadMessageAttachmentsItem(TypedDict, total=False): url: str | 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[MessageAddedPayloadMessageAttachmentsItemVariantsItem] | None - "Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only. `null` otherwise." + "Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only; omitted otherwise." version: int | None "Version number of the attached artifact at the time of attachment. Present on `artifact` type only. `null` otherwise." width: int | None @@ -266,7 +266,7 @@ class MessageAddedPayloadMessage(TypedDict, total=False): "ID of the thread that was branched from this message (`thr_...`). `null` if this message has not spawned a branch thread." content: str | None "Text content of the message. `null` for messages that contain only attachments." - created_at: datetime | None + created_at: str | None "When the message was posted (ISO 8601)." has_replies: bool | None "Whether this message has at least one reply. Only present when explicitly requested or computed by the server." @@ -303,10 +303,10 @@ class MessageAddedPayloadMessage(TypedDict, total=False): team: str | None "ID of the team this message is scoped to (`tem_...`). `null` if the message is not team-scoped." thread: str | None - "ID of the thread this message belongs to (`thr_...`). `null` for messages not yet associated with a thread." + "ID of the thread this message belongs to (`thr_...`)." type: str | 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." - user: str | None + user: str | dict[str, Any] | None "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." visibility: Literal["default", "private"] | None "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." @@ -463,11 +463,11 @@ class MessageUpdatedPayloadMessageAttachmentsItem(TypedDict, total=False): image_width: int | None "Width in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise." media_type: str | None - 'The media category, e.g. `"video"` or `"audio"`. Present on `media` type only. `null` otherwise.' + 'The media category, e.g. `"video"` or `"audio"`. Present on `media` type only; omitted otherwise.' name: str | None "Display name of the media item. Present on `media` type only. `null` otherwise." object: dict[str, Any] | 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`. `null` on other types." + "The full embedded object payload. For `task` type, contains the task record. For `action` type, contains the action definition. For `chart` type, contains the chart with its inline `spec`. Omitted on other types." title: str | None "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: Required[str] @@ -475,7 +475,7 @@ class MessageUpdatedPayloadMessageAttachmentsItem(TypedDict, total=False): url: str | 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[MessageUpdatedPayloadMessageAttachmentsItemVariantsItem] | None - "Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only. `null` otherwise." + "Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only; omitted otherwise." version: int | None "Version number of the attached artifact at the time of attachment. Present on `artifact` type only. `null` otherwise." width: int | None @@ -506,7 +506,7 @@ class MessageUpdatedPayloadMessage(TypedDict, total=False): "ID of the thread that was branched from this message (`thr_...`). `null` if this message has not spawned a branch thread." content: str | None "Text content of the message. `null` for messages that contain only attachments." - created_at: datetime | None + created_at: str | None "When the message was posted (ISO 8601)." has_replies: bool | None "Whether this message has at least one reply. Only present when explicitly requested or computed by the server." @@ -543,10 +543,10 @@ class MessageUpdatedPayloadMessage(TypedDict, total=False): team: str | None "ID of the team this message is scoped to (`tem_...`). `null` if the message is not team-scoped." thread: str | None - "ID of the thread this message belongs to (`thr_...`). `null` for messages not yet associated with a thread." + "ID of the thread this message belongs to (`thr_...`)." type: str | 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." - user: str | None + user: str | dict[str, Any] | None "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." visibility: Literal["default", "private"] | None "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." diff --git a/src/archastro/platform/channels/api_tasks_channel.py b/src/archastro/platform/channels/api_tasks_channel.py index 02ec566..de404da 100644 --- a/src/archastro/platform/channels/api_tasks_channel.py +++ b/src/archastro/platform/channels/api_tasks_channel.py @@ -1,6 +1,6 @@ # Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. # This file is auto-generated by @archastro/sdk-generator. Do not edit. -# Content hash: 4b37f88c4cc7 +# Content hash: 426450fa3df6 from collections.abc import Callable from datetime import datetime @@ -98,6 +98,8 @@ class TasksUpdatedPayloadTasksItem(TypedDict, total=False): "Long-form description or notes for the task. `null` if no description has been provided." due_date: datetime | None "Date and time by which the task should be completed (ISO 8601). `null` if no due date is set." + epic: str | None + "Free-form grouping label. `null` when the task is not in an epic." id: Required[str] "Task ID (`tsk_...`)." is_blocked: bool | None @@ -122,6 +124,12 @@ class TasksUpdatedPayloadTasksItem(TypedDict, total=False): "Priority level of the task from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when not explicitly set." sandbox: str | None "ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment." + source_id: str | None + "Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source." + source_scope: str | 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 + "Kind of source object (for example `repository`). `null` when the task has no source." status: Required[str] 'Current status of the task. One of `"open"`, `"in_progress"`, or `"done"`.' subtasks_count: int | None diff --git a/src/archastro/platform/client.py b/src/archastro/platform/client.py index dff1e4c..fffa8ce 100644 --- a/src/archastro/platform/client.py +++ b/src/archastro/platform/client.py @@ -1,6 +1,6 @@ # Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. # This file is auto-generated by @archastro/sdk-generator. Do not edit. -# Content hash: 7ec220a0ac4f +# Content hash: f24da3972099 from urllib.parse import urlparse, urlunparse @@ -53,6 +53,8 @@ def __init__( self.bug_reports = self.v1.bug_reports self.config = self.v1.config self.custom_objects = self.v1.custom_objects + self.event_subscription_deliveries = self.v1.event_subscription_deliveries + self.event_subscriptions = self.v1.event_subscriptions self.extractions = self.v1.extractions self.files = self.v1.files self.installation_sources = self.v1.installation_sources @@ -284,6 +286,8 @@ def __init__( self.bug_reports = self.v1.bug_reports self.config = self.v1.config self.custom_objects = self.v1.custom_objects + self.event_subscription_deliveries = self.v1.event_subscription_deliveries + self.event_subscriptions = self.v1.event_subscriptions self.extractions = self.v1.extractions self.files = self.v1.files self.installation_sources = self.v1.installation_sources diff --git a/src/archastro/platform/types/__init__.py b/src/archastro/platform/types/__init__.py index 6f6f7c6..9ad95c3 100644 --- a/src/archastro/platform/types/__init__.py +++ b/src/archastro/platform/types/__init__.py @@ -1,6 +1,6 @@ # Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. # This file is auto-generated by @archastro/sdk-generator. Do not edit. -# Content hash: f222744ed267 +# Content hash: e6e437459282 from .ai import * # noqa: F401,F403 from .artifacts import * # noqa: F401,F403 @@ -15,6 +15,7 @@ from .notifications import * # noqa: F401,F403 from .oauth import * # noqa: F401,F403 from .status import * # noqa: F401,F403 +from .system import * # noqa: F401,F403 from .tasks import * # noqa: F401,F403 from .teams import * # noqa: F401,F403 from .threads import * # noqa: F401,F403 diff --git a/src/archastro/platform/types/automations.py b/src/archastro/platform/types/automations.py index 1989ca2..8603d05 100644 --- a/src/archastro/platform/types/automations.py +++ b/src/archastro/platform/types/automations.py @@ -1,6 +1,6 @@ # Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. # This file is auto-generated by @archastro/sdk-generator. Do not edit. -# Content hash: 6e1e4ed81463 +# Content hash: 0e837510897f from datetime import datetime from typing import Any diff --git a/src/archastro/platform/types/common.py b/src/archastro/platform/types/common.py index ae05b63..935115e 100644 --- a/src/archastro/platform/types/common.py +++ b/src/archastro/platform/types/common.py @@ -1,6 +1,6 @@ # Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. # This file is auto-generated by @archastro/sdk-generator. Do not edit. -# Content hash: 0735c429cba4 +# Content hash: 86361fa54a35 from datetime import datetime from typing import Annotated, Any, Literal @@ -406,7 +406,7 @@ class Attachment(BaseModel): ) media_type: str | None = Field( default=None, - description='The media category, e.g. `"video"` or `"audio"`. Present on `media` type only. `null` otherwise.', + description='The media category, e.g. `"video"` or `"audio"`. Present on `media` type only; omitted otherwise.', ) name: str | None = Field( default=None, @@ -414,7 +414,7 @@ class Attachment(BaseModel): ) object: dict[str, Any] | None = Field( default=None, - 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`. `null` on other types.", + description="The full embedded object payload. For `task` type, contains the task record. For `action` type, contains the action definition. For `chart` type, contains the chart with its inline `spec`. Omitted on other types.", ) title: str | None = Field( default=None, @@ -430,7 +430,7 @@ class Attachment(BaseModel): ) variants: list[MediaVariant] | None = Field( default=None, - description="Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only. `null` otherwise.", + description="Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only; omitted otherwise.", ) version: int | None = Field( default=None, @@ -637,7 +637,7 @@ class Message(BaseModel): default=None, description="Text content of the message. `null` for messages that contain only attachments.", ) - created_at: datetime | None = Field( + created_at: str | None = Field( default=None, description="When the message was posted (ISO 8601)." ) has_replies: bool | None = Field( @@ -705,14 +705,13 @@ class Message(BaseModel): description="ID of the team this message is scoped to (`tem_...`). `null` if the message is not team-scoped.", ) thread: str | None = Field( - default=None, - description="ID of the thread this message belongs to (`thr_...`). `null` for messages not yet associated with a thread.", + default=None, description="ID of the thread this message belongs to (`thr_...`)." ) type: str | None = Field( default=None, 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.", ) - user: str | None = Field( + user: str | dict[str, Any] | None = Field( default=None, 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.", ) @@ -1055,6 +1054,125 @@ class Deployment(BaseModel): ) +class DomainEvent(BaseModel): + """ + A domain event with stable attribution fields and an event-specific payload. + """ + + agent: str | None = None + created_at: datetime + event_name: str + id: str + idempotency_key: str | None = None + org: str | None = None + payload: dict[str, Any] = Field( + ..., + description="Opaque event-specific JSON. Use event_name to select the expected payload schema.", + ) + sandbox: str | None = None + team: str | None = None + user: str | None = None + + +class EventSubscription(BaseModel): + """ + An app-scoped subscription to exact domain-event names. + """ + + agent: str | None = None + available_count: int + created_at: datetime + dropped_events_total: int + dropped_through_position: int + event_names: list[str] + id: str + last_overflow_at: datetime | None = None + leased_count: int + max_pending_events: int + name: str + org: str | None = None + queue_epoch: int + retention_seconds: int + sandbox: str | None = None + status: Literal["active", "paused"] + team: str | None = None + updated_at: datetime + user: str | None = None + visibility_timeout_seconds: int + + +class EventSubscriptionDelivery(BaseModel): + """ + A domain event leased from a subscription queue. + """ + + delivery_id: str + event: DomainEvent + lease_expires_at: datetime + receipt_handle: str + receive_count: int + sequence: int + + +class EventSubscriptionClaim(BaseModel): + """ + Result of atomically claiming the head delivery. + """ + + data: list[EventSubscriptionDelivery] + dropped_events_total: int + dropped_through_position: int + has_more: bool + queue_epoch: int + + +class EventSubscriptionQueueEntry(BaseModel): + """ + A non-reserving view of one queued delivery. + """ + + delivery_id: str + event: DomainEvent + lease_expires_at: datetime | None = None + receive_count: int + sequence: int + state: Literal["available", "leased"] + + +class EventSubscriptionHead(BaseModel): + """ + A non-reserving view of the queue head. + """ + + data: EventSubscriptionQueueEntry | None = None + + +class EventSubscriptionPage(BaseModel): + """ + A page of domain-event subscriptions. + """ + + data: list[EventSubscription] + page: int + per_page: int + total_count: int + total_pages: int + + +class EventSubscriptionQueue(BaseModel): + """ + A cursor-paginated non-reserving view of a subscription queue. + """ + + after_cursor: str | None = None + before_cursor: str | None = None + data: list[EventSubscriptionQueueEntry] + dropped_events_total: int + dropped_through_position: int + has_more: bool + queue_epoch: int + + class StorageFile(BaseModel): """ A file stored in the platform's object storage, with metadata and a signed URL for downloading its contents. @@ -1622,6 +1740,37 @@ class PrivateServicePage(BaseModel): total_pages: int +class ProductKnowledgeReconcileFailure(BaseModel): + """ + One stamped customer whose product-knowledge tool update did not converge. + """ + + customer_key: str = Field( + ..., description="Stable vendor-defined key for the customer whose agent did not converge." + ) + error: str = Field(..., description="Stable failure reason for operator and vendor feedback.") + retryable: bool = Field( + ..., description="Whether rerunning the desired-state reconciliation is safe." + ) + + +class ProductKnowledgeReconcileResponse(BaseModel): + """ + Desired-state reconciliation result for a CM install's stamped agents. + """ + + complete: bool = Field( + ..., + description="True when every stamped customer agent now has the desired source allowlist.", + ) + failures: list[ProductKnowledgeReconcileFailure] = Field( + ..., description="Per-customer failures. Empty when reconciliation is complete." + ) + reconciled_customers: list[str] = Field( + ..., description="Customer keys whose agent tool config is converged." + ) + + class RoutinePreset(BaseModel): """ A named preset that defines the execution model and constraints for a routine. Presets are shared definitions; individual routines reference a preset by name. @@ -1856,6 +2005,10 @@ class SlackChannelBinding(BaseModel): default=None, description="Cached value of Slack's `is_private` flag for this channel. May be stale relative to Slack's current state. Private channels are member-managed: mutating the binding requires in-channel evidence.", ) + mirrors: list[str] | None = Field( + default=None, + description="IDs of every mirror thread this channel's messages land in (`thr_ ` public IDs) that the caller can read, including any legacy peel or chain threads. Empty for a caller with no membership on any of them, and for a channel that has not mirrored anything yet. IDs only: reading a mirror's contents still requires membership on it.", + ) muted: bool = Field( ..., description="Whether the resident agent is currently muted. A muted resident keeps mirroring the channel (reading) but stops replying. A timed mute expires automatically at `muted_until`; this reflects the effective state as of now. Defaults to `false`.", @@ -1870,11 +2023,11 @@ class SlackChannelBinding(BaseModel): ) resident_agent: str | None = Field( default=None, - description="ID of the non-concierge agent selected by Slack ingress. `null` when ingress falls back to the concierge.", + description="ID of the resident agent selected by Slack ingress. `null` when no resident is attached and the channel is an observer.", ) - route_kind: Literal["fda", "resident", "concierge"] = Field( + route_kind: Literal["fda", "resident", "observer", "concierge"] = Field( ..., - description="Effective Slack ingress route: `fda` for a team-bound resident, `resident` for an unbound resident, or `concierge` when no non-concierge agent is attached.", + description="Effective Slack ingress route. `fda` a resident on a team-bound channel, replying through the Forward Deployed Agent chain. `resident` a resident on an internal channel, replying through the channel mirror. `observer` no resident is attached, so the channel is recorded and nobody replies. `concierge` no longer returned anywhere; until Track F it was the value for a channel with no resident, meaning the shared concierge agent answered there. The value is retained in this enum so consumers matching on it do not break, and its removal rides a deliberate API change.", ) scope_key: str | None = Field( default=None, @@ -1910,20 +2063,82 @@ class SlackChannelBindingListResponse(BaseModel): ) +class SlackDeliveryOutcome(BaseModel): + """ + What happened to one agent message this platform sent to a Slack channel. Lets you confirm delivery, or find out why a reply never arrived, without reading the channel's mirrored conversation. + """ + + agent: str | None = Field(default=None, description="ID of the agent whose message this was.") + binding: str | None = Field( + default=None, + description="ID of the Slack channel binding in force for this send. `null` when no binding could be resolved, in which case the send was treated as cross-org and floored on that basis.", + ) + channel: str = Field(..., description="Slack channel ID the send was addressed to.") + failure_reason: str | None = Field( + default=None, + description="For a `failed` send, a short machine-readable cause `slack:` when Slack rejected the call, or `floor_config` when the content floor could not be evaluated and the send failed closed.", + ) + guard_kind: str | None = Field( + default=None, + description="For a withheld send, the kind of guard that stopped it `RegexMatch`, `ContainsAny`, `ContainsString`, or `LLMJudge`. `null` when the send was not withheld by a guard.", + ) + guard_labels: list[str] | None = Field( + default=None, + description="For a withheld send, the labels of the guards that stopped it (for example `Contains AWS access key ID`). These are the content policy's own descriptions, recorded as they read at the time of the send; they never contain the withheld message.", + ) + id: str = Field(..., description="Unique identifier for this delivery outcome.") + message: str | None = Field( + default=None, + description="ID of the platform message this attempt was carrying. Reading that message still requires access to its thread this field correlates, it does not grant.", + ) + operation: Literal["post", "post_ephemeral", "update"] = Field( + ..., + description="Which Slack call the attempt made. `post` a new message in the channel, visible to everyone in it. `post_ephemeral` a message only one named channel member could see; Slack returns no durable timestamp for one, so it has no `thread_ts` to correlate and cannot be found in the channel's history afterwards. `update` replacing an existing message (typically a thinking placeholder).", + ) + outcome: Literal["delivered", "floored", "judge_refused", "failed"] = Field( + ..., + description="What happened to the send. `delivered` Slack accepted the message. `floored` a deterministic content guard withheld it, so it never left. `judge_refused` the cross-org judge decided it was not appropriate for this channel's audience. `failed` Slack rejected the call, or the content floor could not be evaluated and the send failed closed.", + ) + recorded_at: datetime = Field(..., description="When the send was attempted.") + thread_ts: str | None = Field( + default=None, + description="Slack thread timestamp the send targeted, letting attempts be grouped into the conversation they belong to. `null` for a top-level channel post.", + ) + + +class SlackDeliveryOutcomeListResponse(BaseModel): + """ + A page of delivery outcomes for one Slack channel, newest first. Page through history with the returned cursors; `since` and `outcome` are filters, not paging controls. + """ + + after_cursor: str | None = Field( + default=None, + description="Opaque cursor for the page of newer outcomes. Pass back as `after_cursor` to poll for attempts recorded since. `null` when the page is empty.", + ) + before_cursor: str | None = Field( + default=None, + description="Opaque cursor for the page of older outcomes. Pass back as `before_cursor` to continue into history. `null` when the page is empty.", + ) + data: list[SlackDeliveryOutcome] = Field( + ..., description="Delivery outcomes matching the query, newest attempt first." + ) + has_more: bool = Field(..., description="True when more outcomes exist beyond this page.") + + class Trajectory(BaseModel): """ A recorded sequence of AI messages and tool interactions representing a single AI reasoning session. Trajectories are stored as structured message logs and can be replayed or inspected after execution. """ - created_at: datetime | None = Field( + created_at: str | None = Field( default=None, description="When the trajectory was recorded (ISO 8601)." ) file: str | None = Field( default=None, - description="ID of the storage file that persists the raw trajectory data (`fil_...`). `null` if the trajectory has not been written to a file.", + description="ID of the storage file that persists the raw trajectory data (`fil_...`).", ) id: str = Field(..., description="Trajectory ID (`trj_...`).") - messages: dict[str, Any] | None = Field( + messages: list[dict[str, Any]] | None = Field( default=None, description="Serialized message log for this trajectory. Contains the ordered sequence of AI and tool messages produced during the session.", ) @@ -1939,7 +2154,7 @@ class Trajectory(BaseModel): default=None, description="ID of the team this trajectory is scoped to (`team_...`). `null` for trajectories not associated with a team.", ) - updated_at: datetime | None = Field( + updated_at: str | None = Field( default=None, description="When the trajectory record was last updated (ISO 8601)." ) @@ -2124,11 +2339,11 @@ class SolutionAutomationTemplateDetails(BaseModel): automation_type: str | None = Field( default=None, - description="Automation execution type (`invoked`, `scheduled`, or `trigger`).", + description="Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", ) invoke_contract: SolutionAutomationInvokeContract | None = Field( default=None, - description="Schema-driven payload and participant inputs for an invoked automation. Used by installation clients to collect locked prefills before provisioning.", + 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.", ) type: Literal["automation"] = Field( default="automation", @@ -2192,7 +2407,7 @@ class SolutionSummary(BaseModel): default=None, description="Category tag keys declared in the Solution body, used to group Solutions in the catalog. An empty array when the body declares none.", ) - created_at: datetime | None = Field( + created_at: str | None = Field( default=None, description="When the Solution config was first imported (ISO 8601)." ) description: str | None = Field( @@ -2277,7 +2492,7 @@ class SolutionSummary(BaseModel): ..., 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.", ) - updated_at: datetime | None = Field( + updated_at: str | None = Field( default=None, description="When the Solution config was last modified (ISO 8601)." ) upgrade_available: bool = Field( @@ -2322,7 +2537,7 @@ class Agent(BaseModel): app: str | None = Field( default=None, description="ID of the application that owns this agent (`dap_...`)." ) - created_at: datetime | None = Field( + created_at: str | None = Field( default=None, description="When the agent was created (ISO 8601)." ) default_model: str | None = Field( @@ -2389,7 +2604,7 @@ class Agent(BaseModel): default=None, 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`).", ) - updated_at: datetime | None = Field( + updated_at: str | None = Field( default=None, description="When the agent was last modified (ISO 8601)." ) user: str | None = Field( @@ -2480,7 +2695,7 @@ class AgentCreateResponse(BaseModel): app: str | None = Field( default=None, description="ID of the app this agent belongs to (`dap_...`)." ) - created_at: datetime | None = Field( + created_at: str | None = Field( default=None, description="When the agent was created (ISO 8601)." ) default_model: str | None = Field( @@ -2531,7 +2746,7 @@ class AgentCreateResponse(BaseModel): default=None, description="ID of the team that owns this agent (`tea_...`). `null` if owned by a user rather than a team.", ) - updated_at: datetime | None = Field( + updated_at: str | None = Field( default=None, description="When the agent record was last modified (ISO 8601)." ) user: str | None = Field( @@ -3569,7 +3784,7 @@ class SolutionImportResponse(BaseModel): The result of importing a Solution bundle into the library, including the Solution config record, a structured import result, and the list of all configs persisted during the transaction. """ - created_at: datetime | None = Field( + created_at: str | None = Field( default=None, description="When the Solution config record was first created (ISO 8601)." ) id: str = Field(..., description="Solution config ID (`cfg_...`).") @@ -3590,7 +3805,7 @@ class SolutionImportResponse(BaseModel): ..., description="Full summary of the imported Solution, in the same shape as the individual Solution retrieval endpoint.", ) - updated_at: datetime | None = Field( + updated_at: str | None = Field( default=None, description="When the Solution config record was last modified (ISO 8601)." ) virtual_path: str | None = Field( diff --git a/src/archastro/platform/types/device.py b/src/archastro/platform/types/device.py index b193951..a058eaf 100644 --- a/src/archastro/platform/types/device.py +++ b/src/archastro/platform/types/device.py @@ -1,10 +1,24 @@ # Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. # This file is auto-generated by @archastro/sdk-generator. Do not edit. -# Content hash: 9947b9c23698 +# Content hash: fae476f561c9 + +from datetime import datetime from pydantic import BaseModel, Field +class DeviceAuthorizationDetailsResponse(BaseModel): + """ + User-visible details for a pending OAuth 2.0 device authorization. + """ + + client_name: str = Field(..., description="Name of the client requesting authorization.") + expires_at: datetime = Field( + ..., description="Expiration time for the pending device authorization." + ) + scopes: list[str] = Field(..., description="Scopes the client is requesting.") + + class DeviceAuthorizationResponse(BaseModel): """ The initial response from an OAuth 2.0 Device Authorization Grant request, containing the codes and URIs needed to complete device authentication. diff --git a/src/archastro/platform/types/image.py b/src/archastro/platform/types/image.py index 24fd1e0..1d21844 100644 --- a/src/archastro/platform/types/image.py +++ b/src/archastro/platform/types/image.py @@ -1,6 +1,6 @@ # Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. # This file is auto-generated by @archastro/sdk-generator. Do not edit. -# Content hash: 811555875cc0 +# Content hash: 05fd04c284ae from pydantic import BaseModel, Field diff --git a/src/archastro/platform/types/system.py b/src/archastro/platform/types/system.py new file mode 100644 index 0000000..4cee8dc --- /dev/null +++ b/src/archastro/platform/types/system.py @@ -0,0 +1,62 @@ +# Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. +# This file is auto-generated by @archastro/sdk-generator. Do not edit. +# Content hash: d15c5f3ba3a8 + +from datetime import datetime + +from pydantic import BaseModel, Field + + +class SystemAccessToken(BaseModel): + """ + A long-lived API credential associated with a system account, used to authenticate server-to-server requests. + """ + + created_at: datetime | None = Field( + default=None, description="When this token was created (ISO 8601)." + ) + created_by_agent_user: str | None = Field( + default=None, + description="Agent user that minted this token (`usr_...`). `null` unless an agent minted it.", + ) + created_by_developer: str | None = Field( + default=None, + description="Developer account that minted this token (`dva_...`). `null` unless minted with a developer token.", + ) + created_by_org: str | None = Field( + default=None, + description="Org of the principal that minted this token (`org_...`). `null` on legacy rows.", + ) + created_by_team: str | None = Field( + default=None, + description="Team that minted this token (`tem_...`). `null` unless minted as a team.", + ) + created_by_user: str | None = Field( + default=None, + description="User who minted this token (`usr_...`). Distinct from the token subject. `null` on legacy rows.", + ) + expires_at: datetime | None = Field( + default=None, + description="When the token expires. `null` on legacy rows that predate stored expiry.", + ) + id: str = Field(..., description="Token ID (`sat_...`).") + last_used_at: datetime | None = Field( + default=None, + description="When this token was last used to authenticate a request. `null` if the token has never been used.", + ) + name: str | None = Field( + default=None, + description="Human-readable label assigned to this token at creation time. `null` when no label was supplied.", + ) + revoked_at: datetime | None = Field( + default=None, + description="When this token was revoked. `null` if the token is still active.", + ) + scopes: str | None = Field( + default=None, + description="Space-separated OAuth scopes stamped on the token. `null` on legacy rows; treat as `full_access`.", + ) + token: str | None = Field( + default=None, + description="Raw bearer token string. Present only in the response to the create request; never returned again after that.", + ) diff --git a/src/archastro/platform/types/tasks.py b/src/archastro/platform/types/tasks.py index 4740338..70b8eb7 100644 --- a/src/archastro/platform/types/tasks.py +++ b/src/archastro/platform/types/tasks.py @@ -1,6 +1,6 @@ # Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. # This file is auto-generated by @archastro/sdk-generator. Do not edit. -# Content hash: 289d30e51747 +# Content hash: 10002b34989e from datetime import datetime from typing import Any @@ -71,6 +71,10 @@ class Task(BaseModel): default=None, description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", ) + epic: str | None = Field( + default=None, + description="Free-form grouping label. `null` when the task is not in an epic.", + ) id: str = Field(..., description="Task ID (`tsk_...`).") is_blocked: bool | None = Field( default=None, @@ -113,6 +117,18 @@ class Task(BaseModel): default=None, description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", ) + source_id: str | None = Field( + default=None, + description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", + ) + source_scope: str | None = Field( + default=None, + 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`.", + ) + source_type: str | None = Field( + default=None, + description="Kind of source object (for example `repository`). `null` when the task has no source.", + ) status: str = Field( ..., description='Current status of the task. One of `"open"`, `"in_progress"`, or `"done"`.', diff --git a/src/archastro/platform/types/teams.py b/src/archastro/platform/types/teams.py index 42c0277..aa4746d 100644 --- a/src/archastro/platform/types/teams.py +++ b/src/archastro/platform/types/teams.py @@ -1,6 +1,6 @@ # Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. # This file is auto-generated by @archastro/sdk-generator. Do not edit. -# Content hash: 11b7ef906e62 +# Content hash: 6263642e67a4 from datetime import datetime from typing import Any diff --git a/src/archastro/platform/types/threads.py b/src/archastro/platform/types/threads.py index 99e6e25..c8fffef 100644 --- a/src/archastro/platform/types/threads.py +++ b/src/archastro/platform/types/threads.py @@ -1,6 +1,6 @@ # Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. # This file is auto-generated by @archastro/sdk-generator. Do not edit. -# Content hash: dac7b47edeed +# Content hash: d7cef8b17ff6 from datetime import datetime from typing import Any, Literal @@ -18,7 +18,7 @@ class ThreadSettings(BaseModel): agent_enabled: bool | None = Field( default=None, - 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.", + 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.", ) @@ -31,7 +31,7 @@ class Thread(BaseModel): default=None, description="ID of the agent that owns this thread (`agt_...`). `null` for user-owned or team-owned threads.", ) - created_at: datetime | None = Field( + created_at: str | None = Field( default=None, description="When the thread was created (ISO 8601)." ) creator: str | dict[str, Any] | None = Field( @@ -65,9 +65,9 @@ class Thread(BaseModel): ) kind: str | None = Field( default=None, - description='Thread subtype: `"standard"` for ordinary threads, `"slack_mirror"` for the membership-strict mirror of a Slack channel, `"slashwork_mirror"` for the membership-strict mirror of a Slashwork group. Read-only derived server-side at creation, never accepted from params.', + description='Thread subtype: `"standard"` for ordinary threads, `"personal"` for a user-and-owned-agents roster, `"slack_mirror"` for the membership-strict mirror of a Slack channel, or `"slashwork_mirror"` for the membership-strict mirror of a Slashwork group. `personal` is an explicit user-thread creation option; mirror kinds are server-derived.', ) - last_activity: datetime | None = Field( + last_activity: str | None = Field( default=None, 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.", ) @@ -127,7 +127,7 @@ class Thread(BaseModel): default=None, description="URL-safe slug for the thread, used in human-readable permalinks. `null` if not assigned.", ) - sub_threads: list[dict[str, Any]] | None = Field( + sub_threads: list[dict[str, Any] | None] | None = Field( default=None, description="Threads that are nested under this thread as replies to a parent message. Present only when sub-thread enrichment is requested.", ) @@ -143,15 +143,15 @@ class Thread(BaseModel): default=None, description="Human-readable name of the thread. `null` if no title has been set.", ) - ttl: int | None = Field( + ttl: str | None = Field( default=None, - description="Time-to-live in seconds after which the thread may be automatically cleaned up. `null` if the thread does not expire.", + description="Offset-free expiry timestamp after which the thread may be automatically cleaned up. `null` if the thread does not expire.", ) unread_count: int | None = Field( default=None, description="Number of messages in this thread that the authenticated user has not yet read. Present only when read-state enrichment is requested.", ) - updated_at: datetime | None = Field( + updated_at: str | None = Field( default=None, description="When the thread was last modified (ISO 8601)." ) user: str | None = Field( diff --git a/src/archastro/platform/types/users.py b/src/archastro/platform/types/users.py index df6ed3f..c67fd55 100644 --- a/src/archastro/platform/types/users.py +++ b/src/archastro/platform/types/users.py @@ -1,6 +1,6 @@ # Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. # This file is auto-generated by @archastro/sdk-generator. Do not edit. -# Content hash: 12165b70a40f +# Content hash: 53d1623c79d0 from datetime import datetime from typing import Any @@ -26,6 +26,26 @@ class User(BaseModel): default=None, description="Display name of the user's app. `null` when the app association was not preloaded by the caller.", ) + created_by_agent_user: str | None = Field( + default=None, + description="Agent user that created this account (`usr_...`). `null` unless an agent created it.", + ) + created_by_developer: str | None = Field( + default=None, + description="Developer account that created this user (`dva_...`). `null` unless created via a developer token.", + ) + created_by_org: str | None = Field( + default=None, + description="Org of the principal that created this user (`org_...`). `null` on legacy rows.", + ) + created_by_team: str | None = Field( + default=None, + description="Team that created this user (`tem_...`). `null` unless created as a team.", + ) + created_by_user: str | None = Field( + default=None, + description="User who created this account (`usr_...`). `null` on self-signup or legacy rows.", + ) email: str | None = Field(default=None, description="Email address of the user.") id: str = Field(..., description="User ID (`usr_...`).") is_system_user: bool | None = Field( @@ -52,6 +72,10 @@ class User(BaseModel): default=None, 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.', ) + org_slug: str | None = Field( + default=None, + 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.", + ) sandbox: str | None = Field( default=None, description="ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.", diff --git a/src/archastro/platform/v1/__init__.py b/src/archastro/platform/v1/__init__.py index 94ca3bf..81ec661 100644 --- a/src/archastro/platform/v1/__init__.py +++ b/src/archastro/platform/v1/__init__.py @@ -1,6 +1,6 @@ # Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. # This file is auto-generated by @archastro/sdk-generator. Do not edit. -# Content hash: 6cffb167deff +# Content hash: 33b7b81d0ce6 from ..runtime.http_client import HttpClient, SyncHttpClient from .resources.activity_feed import ActivityFeedResource, AsyncActivityFeedResource @@ -24,6 +24,11 @@ from .resources.bug_reports import AsyncBugReportResource, BugReportResource from .resources.config import AsyncConfigResource, ConfigResource from .resources.custom_objects import AsyncCustomObjectResource, CustomObjectResource +from .resources.event_subscription_deliveries import ( + AsyncEventSubscriptionDeliveryResource, + EventSubscriptionDeliveryResource, +) +from .resources.event_subscriptions import AsyncEventSubscriptionResource, EventSubscriptionResource from .resources.extractions import AsyncExtractionResource, ExtractionResource from .resources.files import AsyncFileResource, FileResource from .resources.installation_sources import ( @@ -93,6 +98,8 @@ def __init__(self, http: SyncHttpClient): self.bug_reports = BugReportResource(http) self.config = ConfigResource(http) self.custom_objects = CustomObjectResource(http) + self.event_subscription_deliveries = EventSubscriptionDeliveryResource(http) + self.event_subscriptions = EventSubscriptionResource(http) self.extractions = ExtractionResource(http) self.files = FileResource(http) self.installation_sources = InstallationSourceResource(http) @@ -145,6 +152,8 @@ def __init__(self, http: HttpClient): self.bug_reports = AsyncBugReportResource(http) self.config = AsyncConfigResource(http) self.custom_objects = AsyncCustomObjectResource(http) + self.event_subscription_deliveries = AsyncEventSubscriptionDeliveryResource(http) + self.event_subscriptions = AsyncEventSubscriptionResource(http) self.extractions = AsyncExtractionResource(http) self.files = AsyncFileResource(http) self.installation_sources = AsyncInstallationSourceResource(http) diff --git a/src/archastro/platform/v1/resources/__init__.py b/src/archastro/platform/v1/resources/__init__.py index 62a6bb8..bd1191b 100644 --- a/src/archastro/platform/v1/resources/__init__.py +++ b/src/archastro/platform/v1/resources/__init__.py @@ -1,6 +1,6 @@ # Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. # This file is auto-generated by @archastro/sdk-generator. Do not edit. -# Content hash: a3f1312393cb +# Content hash: 08b6aec85d81 from .activity_feed import ( ActivityFeedResource, # noqa: F401 @@ -74,6 +74,14 @@ AsyncCustomObjectResource, # noqa: F401 CustomObjectResource, # noqa: F401 ) +from .event_subscription_deliveries import ( + AsyncEventSubscriptionDeliveryResource, # noqa: F401 + EventSubscriptionDeliveryResource, # noqa: F401 +) +from .event_subscriptions import ( + AsyncEventSubscriptionResource, # noqa: F401 + EventSubscriptionResource, # noqa: F401 +) from .extractions import ( AsyncExtractionResource, # noqa: F401 ExtractionResource, # noqa: F401 diff --git a/src/archastro/platform/v1/resources/agents.py b/src/archastro/platform/v1/resources/agents.py index 805f484..343cc97 100644 --- a/src/archastro/platform/v1/resources/agents.py +++ b/src/archastro/platform/v1/resources/agents.py @@ -1,6 +1,6 @@ # Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. # This file is auto-generated by @archastro/sdk-generator. Do not edit. -# Content hash: 3473c15972ad +# Content hash: 655ad9482090 from __future__ import annotations @@ -555,7 +555,7 @@ class AgentThreadsInputThreadProfilePicture(TypedDict, total=False): class AgentThreadsInputThreadSettings(TypedDict, total=False): agent_enabled: bool | None - "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." + "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 AgentThreadsInputThread(TypedDict, total=False): @@ -567,6 +567,8 @@ class AgentThreadsInputThread(TypedDict, total=False): "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: Literal["personal"] | None + "Optional behavioral subtype. `personal` is accepted only for a user-owned thread and limits membership to that user and agents currently owned by them. Mirror kinds remain server-derived and cannot be selected by callers." members: list[AgentThreadsInputThreadMembersItem] | 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, Any] | None diff --git a/src/archastro/platform/v1/resources/event_subscription_deliveries.py b/src/archastro/platform/v1/resources/event_subscription_deliveries.py new file mode 100644 index 0000000..6510620 --- /dev/null +++ b/src/archastro/platform/v1/resources/event_subscription_deliveries.py @@ -0,0 +1,66 @@ +# Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. +# This file is auto-generated by @archastro/sdk-generator. Do not edit. +# Content hash: 3749fa3117f0 + +from __future__ import annotations + +from typing import TypedDict + +from ...runtime.http_client import HttpClient, SyncHttpClient + + +class EventSubscriptionDeliveryAcknowledgeInput(TypedDict): + "Acknowledge a claimed event" + + receipt_handle: str + "Opaque handle returned by claim." + + +class AsyncEventSubscriptionDeliveryResource: + def __init__(self, http: HttpClient): + self._http = http + + async def acknowledge( + self, delivery: str, input: EventSubscriptionDeliveryAcknowledgeInput + ) -> None: + """ + Acknowledge a claimed event + Acknowledges a delivery using its current receipt handle. Repeating the same acknowledgement is idempotent; a stale or incorrect receipt returns 409. Acknowledging a delivery that aged out under the subscription's retention returns `delivery_not_found` the event was already counted in `dropped_events_total`, and the acknowledgement should not be retried. + + Args: + delivery: Delivery ID (`esd_...`). + input: Request body. + input.receipt_handle: Opaque handle returned by claim. + + Returns: + No content + """ + await self._http.request( + f"/api/v1/event_subscription_deliveries/{delivery}/acknowledge", + method="POST", + body=input, + ) + + +class EventSubscriptionDeliveryResource: + def __init__(self, http: SyncHttpClient): + self._http = http + + def acknowledge(self, delivery: str, input: EventSubscriptionDeliveryAcknowledgeInput) -> None: + """ + Acknowledge a claimed event + Acknowledges a delivery using its current receipt handle. Repeating the same acknowledgement is idempotent; a stale or incorrect receipt returns 409. Acknowledging a delivery that aged out under the subscription's retention returns `delivery_not_found` the event was already counted in `dropped_events_total`, and the acknowledgement should not be retried. + + Args: + delivery: Delivery ID (`esd_...`). + input: Request body. + input.receipt_handle: Opaque handle returned by claim. + + Returns: + No content + """ + self._http.request( + f"/api/v1/event_subscription_deliveries/{delivery}/acknowledge", + method="POST", + body=input, + ) diff --git a/src/archastro/platform/v1/resources/event_subscriptions.py b/src/archastro/platform/v1/resources/event_subscriptions.py new file mode 100644 index 0000000..94970a2 --- /dev/null +++ b/src/archastro/platform/v1/resources/event_subscriptions.py @@ -0,0 +1,420 @@ +# Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. +# This file is auto-generated by @archastro/sdk-generator. Do not edit. +# Content hash: ee8786d0c9ca + +from __future__ import annotations + +from typing import Literal, Required, TypedDict + +from ...runtime.http_client import HttpClient, SyncHttpClient +from ...types.common import ( + EventSubscription, + EventSubscriptionClaim, + EventSubscriptionHead, + EventSubscriptionPage, + EventSubscriptionQueue, +) + + +class EventSubscriptionCreateInput(TypedDict, total=False): + "Create a domain-event subscription" + + event_names: Required[list[str]] + "Exact event names to receive." + max_pending_events: int | None + "Queue cap. Defaults to 100; maximum 1000." + name: Required[str] + "Customer-defined subscription name." + retention_seconds: int | None + "Delivery retention in seconds. Defaults to 86400 (24 hours); between 7200 and 2592000. Applies to future deliveries only." + status: Literal["active", "paused"] | None + "Initial status. Defaults to active." + visibility_timeout_seconds: int | None + "Default claim lease in seconds. Defaults to 300." + + +class EventSubscriptionUpdateInput(TypedDict, total=False): + "Update a domain-event subscription" + + event_names: list[str] | None + max_pending_events: int | None + name: str | None + retention_seconds: int | None + "Delivery retention in seconds. Defaults to 86400 (24 hours); between 7200 and 2592000. Applies to future deliveries only." + status: Literal["active", "paused"] | None + visibility_timeout_seconds: int | None + + +class EventSubscriptionClaimInput(TypedDict, total=False): + "Claim events from a subscription" + + consumer_id: str | None + "Consumer identity between 1 and 128 bytes, recorded on the lease for attribution." + max_events: int | None + "Opts into batch mode: leases up to this many lease-available deliveries (between 1 and 20) in sequence order, skipping leased entries instead of blocking on the head. Omit to keep strict head-of-line semantics." + request_id: str | None + "Idempotency key between 1 and 128 bytes. Use a value unique per claim attempt (e.g. a UUID) the key is scoped to the subscription, so a reused value takes over whatever leases it last stamped. Retrying a claim with the same request_id while its leases are unexpired returns the same deliveries (regardless of max_events) with fresh receipt handles and refreshed leases." + visibility_timeout_seconds: int | None + "Lease duration override between 15 and 3600 seconds." + wait_seconds: int | None + "Long-poll bound between 0 and 20 seconds. When the queue is empty, the request waits up to this long for a delivery before returning an empty data array. 0 (or omitting) returns immediately." + + +class AsyncEventSubscriptionResource: + def __init__(self, http: HttpClient): + self._http = http + + async def list( + self, *, page: int | None = None, per_page: int | None = None + ) -> EventSubscriptionPage: + """ + List domain-event subscriptions + Lists the subscriptions visible to the caller, with current queue counters. + + Args: + page: Page number, starting at 1. + per_page: Subscriptions per page, from 1 through 100. + + Returns: + Subscriptions visible to this caller. + """ + query: dict[str, object] = {} + if page is not None: + query["page"] = page + if per_page is not None: + query["per_page"] = per_page + return await self._http.request( + "/api/v1/event_subscriptions", + query=query, + response_type=EventSubscriptionPage, + ) + + async def create(self, input: EventSubscriptionCreateInput) -> EventSubscription: + """ + Create a domain-event subscription + Creates a durable subscription that receives exportable domain events matching its exact event names. Matching events fan out into a per-subscription queue bounded by max_pending_events and retention_seconds; consume with claim and acknowledge. + + Args: + input: Request body. + input.event_names: Exact event names to receive. + input.max_pending_events: Queue cap. Defaults to 100; maximum 1000. + input.name: Customer-defined subscription name. + input.retention_seconds: Delivery retention in seconds. Defaults to 86400 (24 hours); between 7200 and 2592000. Applies to future deliveries only. + input.status: Initial status. Defaults to active. + input.visibility_timeout_seconds: Default claim lease in seconds. Defaults to 300. + + Returns: + The new volatile subscription. + """ + return await self._http.request( + "/api/v1/event_subscriptions", + method="POST", + body=input, + response_type=EventSubscription, + ) + + async def delete(self, subscription: str) -> None: + """ + Delete a domain-event subscription + Deletes the subscription and every delivery still in its queue. + + Args: + subscription: Subscription ID (`esub_...`). + + Returns: + No content + """ + await self._http.request(f"/api/v1/event_subscriptions/{subscription}", method="DELETE") + + async def get(self, subscription: str) -> EventSubscription: + """ + Get a domain-event subscription + Returns one subscription and its current queue counters. + + Args: + subscription: Subscription ID (`esub_...`). + + Returns: + Successful response + """ + return await self._http.request( + f"/api/v1/event_subscriptions/{subscription}", + response_type=EventSubscription, + ) + + async def update( + self, subscription: str, input: EventSubscriptionUpdateInput + ) -> EventSubscription: + """ + Update a domain-event subscription + Updates matching, status, or queue limits for future fanout. Already queued deliveries remain unless a lower cap trims the oldest entries; retention changes apply to future deliveries only. + + Args: + subscription: Subscription ID (`esub_...`). + input: Request body. + input.retention_seconds: Delivery retention in seconds. Defaults to 86400 (24 hours); between 7200 and 2592000. Applies to future deliveries only. + + Returns: + Successful response + """ + return await self._http.request( + f"/api/v1/event_subscriptions/{subscription}", + method="PATCH", + body=input, + response_type=EventSubscription, + ) + + async def claim( + self, subscription: str, input: EventSubscriptionClaimInput + ) -> EventSubscriptionClaim: + """ + Claim events from a subscription + Atomically leases the oldest unacknowledged delivery. Returns an empty data array when the queue is empty or its head already has an active lease. Passing max_events opts into batch mode, where leased entries are skipped instead of blocking; wait_seconds bounds a long poll on an empty queue. + + Args: + subscription: Subscription ID (`esub_...`). + input: Request body. + input.consumer_id: Consumer identity between 1 and 128 bytes, recorded on the lease for attribution. + input.max_events: Opts into batch mode: leases up to this many lease-available deliveries (between 1 and 20) in sequence order, skipping leased entries instead of blocking on the head. Omit to keep strict head-of-line semantics. + input.request_id: Idempotency key between 1 and 128 bytes. Use a value unique per claim attempt (e.g. a UUID) the key is scoped to the subscription, so a reused value takes over whatever leases it last stamped. Retrying a claim with the same request_id while its leases are unexpired returns the same deliveries (regardless of max_events) with fresh receipt handles and refreshed leases. + input.visibility_timeout_seconds: Lease duration override between 15 and 3600 seconds. + input.wait_seconds: Long-poll bound between 0 and 20 seconds. When the queue is empty, the request waits up to this long for a delivery before returning an empty data array. 0 (or omitting) returns immediately. + + Returns: + Successful response + """ + return await self._http.request( + f"/api/v1/event_subscriptions/{subscription}/claim", + method="POST", + body=input, + response_type=EventSubscriptionClaim, + ) + + async def head(self, subscription: str) -> EventSubscriptionHead: + """ + Peek at the head of a subscription queue + Returns the oldest unacknowledged delivery without reserving it. This diagnostic read cannot be used as a safe substitute for claim. + + Args: + subscription: Subscription ID (`esub_...`). + + Returns: + Successful response + """ + return await self._http.request( + f"/api/v1/event_subscriptions/{subscription}/head", + response_type=EventSubscriptionHead, + ) + + async def queue( + self, + subscription: str, + *, + limit: int | None = None, + before_cursor: str | None = None, + after_cursor: str | None = None, + ) -> EventSubscriptionQueue: + """ + Read a subscription queue + Returns a non-reserving, oldest-first view of unacknowledged deliveries, including the queue's loss indicators (queue_epoch, dropped_events_total, dropped_through_position). Use claim to obtain a receipt handle before acknowledging. + + Args: + subscription: Subscription ID (`esub_...`). + limit: Maximum entries to return, from 1 through 100. + before_cursor: Opaque cursor for the preceding page. + after_cursor: Opaque cursor for the following page. + + Returns: + Successful response + """ + query: dict[str, object] = {} + if limit is not None: + query["limit"] = limit + if before_cursor is not None: + query["before_cursor"] = before_cursor + if after_cursor is not None: + query["after_cursor"] = after_cursor + return await self._http.request( + f"/api/v1/event_subscriptions/{subscription}/queue", + query=query, + response_type=EventSubscriptionQueue, + ) + + +class EventSubscriptionResource: + def __init__(self, http: SyncHttpClient): + self._http = http + + def list( + self, *, page: int | None = None, per_page: int | None = None + ) -> EventSubscriptionPage: + """ + List domain-event subscriptions + Lists the subscriptions visible to the caller, with current queue counters. + + Args: + page: Page number, starting at 1. + per_page: Subscriptions per page, from 1 through 100. + + Returns: + Subscriptions visible to this caller. + """ + query: dict[str, object] = {} + if page is not None: + query["page"] = page + if per_page is not None: + query["per_page"] = per_page + return self._http.request( + "/api/v1/event_subscriptions", + query=query, + response_type=EventSubscriptionPage, + ) + + def create(self, input: EventSubscriptionCreateInput) -> EventSubscription: + """ + Create a domain-event subscription + Creates a durable subscription that receives exportable domain events matching its exact event names. Matching events fan out into a per-subscription queue bounded by max_pending_events and retention_seconds; consume with claim and acknowledge. + + Args: + input: Request body. + input.event_names: Exact event names to receive. + input.max_pending_events: Queue cap. Defaults to 100; maximum 1000. + input.name: Customer-defined subscription name. + input.retention_seconds: Delivery retention in seconds. Defaults to 86400 (24 hours); between 7200 and 2592000. Applies to future deliveries only. + input.status: Initial status. Defaults to active. + input.visibility_timeout_seconds: Default claim lease in seconds. Defaults to 300. + + Returns: + The new volatile subscription. + """ + return self._http.request( + "/api/v1/event_subscriptions", + method="POST", + body=input, + response_type=EventSubscription, + ) + + def delete(self, subscription: str) -> None: + """ + Delete a domain-event subscription + Deletes the subscription and every delivery still in its queue. + + Args: + subscription: Subscription ID (`esub_...`). + + Returns: + No content + """ + self._http.request(f"/api/v1/event_subscriptions/{subscription}", method="DELETE") + + def get(self, subscription: str) -> EventSubscription: + """ + Get a domain-event subscription + Returns one subscription and its current queue counters. + + Args: + subscription: Subscription ID (`esub_...`). + + Returns: + Successful response + """ + return self._http.request( + f"/api/v1/event_subscriptions/{subscription}", + response_type=EventSubscription, + ) + + def update(self, subscription: str, input: EventSubscriptionUpdateInput) -> EventSubscription: + """ + Update a domain-event subscription + Updates matching, status, or queue limits for future fanout. Already queued deliveries remain unless a lower cap trims the oldest entries; retention changes apply to future deliveries only. + + Args: + subscription: Subscription ID (`esub_...`). + input: Request body. + input.retention_seconds: Delivery retention in seconds. Defaults to 86400 (24 hours); between 7200 and 2592000. Applies to future deliveries only. + + Returns: + Successful response + """ + return self._http.request( + f"/api/v1/event_subscriptions/{subscription}", + method="PATCH", + body=input, + response_type=EventSubscription, + ) + + def claim( + self, subscription: str, input: EventSubscriptionClaimInput + ) -> EventSubscriptionClaim: + """ + Claim events from a subscription + Atomically leases the oldest unacknowledged delivery. Returns an empty data array when the queue is empty or its head already has an active lease. Passing max_events opts into batch mode, where leased entries are skipped instead of blocking; wait_seconds bounds a long poll on an empty queue. + + Args: + subscription: Subscription ID (`esub_...`). + input: Request body. + input.consumer_id: Consumer identity between 1 and 128 bytes, recorded on the lease for attribution. + input.max_events: Opts into batch mode: leases up to this many lease-available deliveries (between 1 and 20) in sequence order, skipping leased entries instead of blocking on the head. Omit to keep strict head-of-line semantics. + input.request_id: Idempotency key between 1 and 128 bytes. Use a value unique per claim attempt (e.g. a UUID) the key is scoped to the subscription, so a reused value takes over whatever leases it last stamped. Retrying a claim with the same request_id while its leases are unexpired returns the same deliveries (regardless of max_events) with fresh receipt handles and refreshed leases. + input.visibility_timeout_seconds: Lease duration override between 15 and 3600 seconds. + input.wait_seconds: Long-poll bound between 0 and 20 seconds. When the queue is empty, the request waits up to this long for a delivery before returning an empty data array. 0 (or omitting) returns immediately. + + Returns: + Successful response + """ + return self._http.request( + f"/api/v1/event_subscriptions/{subscription}/claim", + method="POST", + body=input, + response_type=EventSubscriptionClaim, + ) + + def head(self, subscription: str) -> EventSubscriptionHead: + """ + Peek at the head of a subscription queue + Returns the oldest unacknowledged delivery without reserving it. This diagnostic read cannot be used as a safe substitute for claim. + + Args: + subscription: Subscription ID (`esub_...`). + + Returns: + Successful response + """ + return self._http.request( + f"/api/v1/event_subscriptions/{subscription}/head", + response_type=EventSubscriptionHead, + ) + + def queue( + self, + subscription: str, + *, + limit: int | None = None, + before_cursor: str | None = None, + after_cursor: str | None = None, + ) -> EventSubscriptionQueue: + """ + Read a subscription queue + Returns a non-reserving, oldest-first view of unacknowledged deliveries, including the queue's loss indicators (queue_epoch, dropped_events_total, dropped_through_position). Use claim to obtain a receipt handle before acknowledging. + + Args: + subscription: Subscription ID (`esub_...`). + limit: Maximum entries to return, from 1 through 100. + before_cursor: Opaque cursor for the preceding page. + after_cursor: Opaque cursor for the following page. + + Returns: + Successful response + """ + query: dict[str, object] = {} + if limit is not None: + query["limit"] = limit + if before_cursor is not None: + query["before_cursor"] = before_cursor + if after_cursor is not None: + query["after_cursor"] = after_cursor + return self._http.request( + f"/api/v1/event_subscriptions/{subscription}/queue", + query=query, + response_type=EventSubscriptionQueue, + ) diff --git a/src/archastro/platform/v1/resources/oauth.py b/src/archastro/platform/v1/resources/oauth.py index 7682078..0939559 100644 --- a/src/archastro/platform/v1/resources/oauth.py +++ b/src/archastro/platform/v1/resources/oauth.py @@ -1,6 +1,6 @@ # Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. # This file is auto-generated by @archastro/sdk-generator. Do not edit. -# Content hash: f2bc4e9d2692 +# Content hash: fc8f712c2ee7 from __future__ import annotations @@ -9,7 +9,11 @@ from pydantic import BaseModel, Field from ...runtime.http_client import HttpClient, SyncHttpClient -from ...types.device import DeviceAuthorizationResponse, DeviceAuthorizationStatusResponse +from ...types.device import ( + DeviceAuthorizationDetailsResponse, + DeviceAuthorizationResponse, + DeviceAuthorizationStatusResponse, +) from ...types.oauth import OAuthTokenResponse @@ -100,6 +104,27 @@ async def approve(self, input: DeviceApproveInput) -> DeviceAuthorizationStatusR response_type=DeviceAuthorizationStatusResponse, ) + async def authorization(self, code: str) -> DeviceAuthorizationDetailsResponse: + """ + Inspect a pending device authorization + Returns the client name, requested scopes, and expiration for a pending + device authorization owned by the calling app. The caller must be an + authenticated user. This endpoint never approves the request. + + Args: + code: User-facing device authorization code. + + Returns: + Successful response + """ + query: dict[str, object] = {} + query["code"] = code + return await self._http.request( + "/oauth/device/authorization", + query=query, + response_type=DeviceAuthorizationDetailsResponse, + ) + async def authorize(self, input: DeviceAuthorizeInput) -> DeviceAuthorizationResponse: """ Initiate a device authorization request @@ -243,6 +268,27 @@ def approve(self, input: DeviceApproveInput) -> DeviceAuthorizationStatusRespons response_type=DeviceAuthorizationStatusResponse, ) + def authorization(self, code: str) -> DeviceAuthorizationDetailsResponse: + """ + Inspect a pending device authorization + Returns the client name, requested scopes, and expiration for a pending + device authorization owned by the calling app. The caller must be an + authenticated user. This endpoint never approves the request. + + Args: + code: User-facing device authorization code. + + Returns: + Successful response + """ + query: dict[str, object] = {} + query["code"] = code + return self._http.request( + "/oauth/device/authorization", + query=query, + response_type=DeviceAuthorizationDetailsResponse, + ) + def authorize(self, input: DeviceAuthorizeInput) -> DeviceAuthorizationResponse: """ Initiate a device authorization request diff --git a/src/archastro/platform/v1/resources/slack_channel_bindings.py b/src/archastro/platform/v1/resources/slack_channel_bindings.py index b14266d..ed4893e 100644 --- a/src/archastro/platform/v1/resources/slack_channel_bindings.py +++ b/src/archastro/platform/v1/resources/slack_channel_bindings.py @@ -1,16 +1,20 @@ # Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. # This file is auto-generated by @archastro/sdk-generator. Do not edit. -# Content hash: 19dd9e7eab54 +# Content hash: 739c91726193 from __future__ import annotations import builtins -from typing import Any, Required, TypedDict +from typing import Any, Literal, Required, TypedDict from pydantic import BaseModel, Field from ...runtime.http_client import HttpClient, SyncHttpClient -from ...types.common import SlackChannelBinding, SlackChannelBindingListResponse +from ...types.common import ( + SlackChannelBinding, + SlackChannelBindingListResponse, + SlackDeliveryOutcomeListResponse, +) class SlackChannelBindingCreateInput(TypedDict, total=False): @@ -258,6 +262,63 @@ async def get(self, channel: str, slack_team_id: str) -> SlackChannelBinding: response_type=SlackChannelBinding, ) + async def delivery_outcomes( + self, + channel: str, + *, + since: str | None = None, + outcome: Literal["delivered", "floored", "judge_refused", "failed"] | None = None, + limit: int | None = None, + before_cursor: str | None = None, + after_cursor: str | None = None, + ) -> SlackDeliveryOutcomeListResponse: + """ + List delivery outcomes for a Slack channel + Returns what happened to each agent message this platform sent to a Slack + channel, newest attempt first. + A message that never appears in a Slack channel has several possible causes + that look identical from the channel itself: a content guard withheld it, the + cross-org judge refused it, Slack rejected the call, or nobody asked anything. + This endpoint tells them apart. Use it to confirm a reply was delivered, or to + find out why one never arrived, without reading the channel's mirrored + conversation. + Outcomes cover **outbound agent messages only**. They carry no message + content, no author, and nothing about inbound messages. Access follows the + channel's binding the organization and app the channel is bound to and + needs no membership in the mirrored thread. + Paginated with opaque cursors, newest first. When `has_more` is true, pass the + response's `before_cursor` back as `before_cursor` to continue into older + history. `since` and `outcome` narrow the result set; they are filters, not + paging controls. + + Args: + channel: Slack channel ID to read delivery outcomes for (e.g. `C01234ABCDE`). + since: Only return attempts at or after this ISO 8601 timestamp (e.g. `2026-08-11T00:00:00Z`). Omit to return the most recent attempts regardless of age. + outcome: Return only attempts with this outcome. Omit to return every outcome. Use `floored` and `judge_refused` to see only what was withheld. + limit: Maximum number of outcomes to return. Defaults to 50; maximum is 200. + before_cursor: Opaque cursor from a previous response; returns outcomes older than it. Cursors are not parseable and are only valid against this endpoint. + after_cursor: Opaque cursor from a previous response; returns outcomes newer than it. Suited to a UI loading newer entries. To poll for everything recorded since a point in time, prefer `since` with a little overlap and de-duplicate on `id` `after_cursor` can miss an attempt recorded in the same millisecond as the cursor's own row. + + Returns: + Delivery outcomes for the requested channel, newest first. + """ + query: dict[str, object] = {} + if since is not None: + query["since"] = since + if outcome is not None: + query["outcome"] = outcome + if limit is not None: + query["limit"] = limit + if before_cursor is not None: + query["before_cursor"] = before_cursor + if after_cursor is not None: + query["after_cursor"] = after_cursor + return await self._http.request( + f"/api/v1/slack_channel_bindings/{channel}/delivery_outcomes", + query=query, + response_type=SlackDeliveryOutcomeListResponse, + ) + async def deposit_thread( self, channel: str, input: SlackChannelBindingDepositThreadInput ) -> SlackChannelBinding: @@ -473,6 +534,63 @@ def get(self, channel: str, slack_team_id: str) -> SlackChannelBinding: response_type=SlackChannelBinding, ) + def delivery_outcomes( + self, + channel: str, + *, + since: str | None = None, + outcome: Literal["delivered", "floored", "judge_refused", "failed"] | None = None, + limit: int | None = None, + before_cursor: str | None = None, + after_cursor: str | None = None, + ) -> SlackDeliveryOutcomeListResponse: + """ + List delivery outcomes for a Slack channel + Returns what happened to each agent message this platform sent to a Slack + channel, newest attempt first. + A message that never appears in a Slack channel has several possible causes + that look identical from the channel itself: a content guard withheld it, the + cross-org judge refused it, Slack rejected the call, or nobody asked anything. + This endpoint tells them apart. Use it to confirm a reply was delivered, or to + find out why one never arrived, without reading the channel's mirrored + conversation. + Outcomes cover **outbound agent messages only**. They carry no message + content, no author, and nothing about inbound messages. Access follows the + channel's binding the organization and app the channel is bound to and + needs no membership in the mirrored thread. + Paginated with opaque cursors, newest first. When `has_more` is true, pass the + response's `before_cursor` back as `before_cursor` to continue into older + history. `since` and `outcome` narrow the result set; they are filters, not + paging controls. + + Args: + channel: Slack channel ID to read delivery outcomes for (e.g. `C01234ABCDE`). + since: Only return attempts at or after this ISO 8601 timestamp (e.g. `2026-08-11T00:00:00Z`). Omit to return the most recent attempts regardless of age. + outcome: Return only attempts with this outcome. Omit to return every outcome. Use `floored` and `judge_refused` to see only what was withheld. + limit: Maximum number of outcomes to return. Defaults to 50; maximum is 200. + before_cursor: Opaque cursor from a previous response; returns outcomes older than it. Cursors are not parseable and are only valid against this endpoint. + after_cursor: Opaque cursor from a previous response; returns outcomes newer than it. Suited to a UI loading newer entries. To poll for everything recorded since a point in time, prefer `since` with a little overlap and de-duplicate on `id` `after_cursor` can miss an attempt recorded in the same millisecond as the cursor's own row. + + Returns: + Delivery outcomes for the requested channel, newest first. + """ + query: dict[str, object] = {} + if since is not None: + query["since"] = since + if outcome is not None: + query["outcome"] = outcome + if limit is not None: + query["limit"] = limit + if before_cursor is not None: + query["before_cursor"] = before_cursor + if after_cursor is not None: + query["after_cursor"] = after_cursor + return self._http.request( + f"/api/v1/slack_channel_bindings/{channel}/delivery_outcomes", + query=query, + response_type=SlackDeliveryOutcomeListResponse, + ) + def deposit_thread( self, channel: str, input: SlackChannelBindingDepositThreadInput ) -> SlackChannelBinding: diff --git a/src/archastro/platform/v1/resources/solutions.py b/src/archastro/platform/v1/resources/solutions.py index 7c0785e..85de5ff 100644 --- a/src/archastro/platform/v1/resources/solutions.py +++ b/src/archastro/platform/v1/resources/solutions.py @@ -1,6 +1,6 @@ # Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. # This file is auto-generated by @archastro/sdk-generator. Do not edit. -# Content hash: ba1d4f7e9932 +# Content hash: 593cc7ef4728 from __future__ import annotations @@ -9,6 +9,7 @@ from ...runtime.http_client import HttpClient, SyncHttpClient from ...types.common import ( + ProductKnowledgeReconcileResponse, SolutionDependentsResponse, SolutionImportResponse, SolutionInstallResponse, @@ -632,6 +633,26 @@ async def readme(self, solution: str, token: str, *, file: str | None = None) -> query["file"] = file return await self._http.request_raw(f"/api/v1/solutions/{solution}/readme", query=query) + async def reconcile_product_knowledge(self, solution: str) -> ProductKnowledgeReconcileResponse: + """ + Reconcile Customer Management product knowledge + Recomputes every stamped customer's knowledge-search source allowlist + from the template-resolved customer refs plus the install's current marked + product-knowledge sources. Safe to retry; partial failures are returned by + customer key rather than hidden behind an aggregate success. + + Args: + solution: Installed Customer Management Solution config (`cfg_...`) to reconcile. + + Returns: + Per-customer convergence result for this installed solution. + """ + return await self._http.request( + f"/api/v1/solutions/{solution}/reconcile_product_knowledge", + method="POST", + response_type=ProductKnowledgeReconcileResponse, + ) + async def upgrade(self, solution: str, input: SolutionUpgradeInput) -> SolutionUpgradeResponse: """ Upgrade an installed Solution @@ -971,6 +992,26 @@ def readme(self, solution: str, token: str, *, file: str | None = None) -> dict[ query["file"] = file return self._http.request_raw(f"/api/v1/solutions/{solution}/readme", query=query) + def reconcile_product_knowledge(self, solution: str) -> ProductKnowledgeReconcileResponse: + """ + Reconcile Customer Management product knowledge + Recomputes every stamped customer's knowledge-search source allowlist + from the template-resolved customer refs plus the install's current marked + product-knowledge sources. Safe to retry; partial failures are returned by + customer key rather than hidden behind an aggregate success. + + Args: + solution: Installed Customer Management Solution config (`cfg_...`) to reconcile. + + Returns: + Per-customer convergence result for this installed solution. + """ + return self._http.request( + f"/api/v1/solutions/{solution}/reconcile_product_knowledge", + method="POST", + response_type=ProductKnowledgeReconcileResponse, + ) + def upgrade(self, solution: str, input: SolutionUpgradeInput) -> SolutionUpgradeResponse: """ Upgrade an installed Solution diff --git a/src/archastro/platform/v1/resources/tasks.py b/src/archastro/platform/v1/resources/tasks.py index 1be18d0..d5674fe 100644 --- a/src/archastro/platform/v1/resources/tasks.py +++ b/src/archastro/platform/v1/resources/tasks.py @@ -1,6 +1,6 @@ # Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. # This file is auto-generated by @archastro/sdk-generator. Do not edit. -# Content hash: 2006b8dae902 +# Content hash: 0a1524a2c202 from __future__ import annotations @@ -56,6 +56,8 @@ class LeaseCreateInput(TypedDict, total=False): "Requested lease lifetime in seconds; the task aggregate enforces its bounds." lease_id: Required[str] "Caller-generated lease UUID." + require_ready: bool | None + "Conservatively reject the claim when the current task projection has unfinished blockers." session_id: Required[str] "Caller-generated coding-session UUID." session_name: Required[str] @@ -73,6 +75,17 @@ class LeaseRenewInput(TypedDict, total=False): "Current coding-session UUID." +class LinkCreateInput(TypedDict): + "Add an external link to a task" + + external_scope: str + "External container ID." + object_id: str + "External object ID." + object_type: str + "External object type." + + class TaskReplaceInput(TypedDict, total=False): "Update a task" @@ -82,6 +95,8 @@ class TaskReplaceInput(TypedDict, total=False): "Updated long-form description." due_date: datetime | None "Updated due date in ISO 8601 format, or null to clear it." + epic: str | None + "Replacement grouping label. Pass null to clear it." lease_id: str | None "Current caller-held lease UUID. Must be paired with `lease_session_id`." lease_session_id: str | None @@ -102,6 +117,12 @@ class TaskReplaceInput(TypedDict, total=False): "Move this task under a top-level parent (`tsk_...`), or pass null to promote it to a top-level task. A task that has subtasks cannot become one." priority: int | None "Updated priority from 0 (highest) to 4 (lowest)." + source_id: str | None + "Replacement source object identity. Must be supplied with the other source fields." + source_scope: str | None + "Replacement source container. Pass together with `source_type` and `source_id`, or pass all three as null to clear the source." + source_type: str | None + "Replacement source object kind. Must be supplied with the other source fields." status: str | None "Updated status: `open`, `in_progress`, or `done`." tags: list[str] | None @@ -261,6 +282,10 @@ class BlockerListResponseDataItem(BaseModel): default=None, description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", ) + epic: str | None = Field( + default=None, + description="Free-form grouping label. `null` when the task is not in an epic.", + ) id: str = Field(..., description="Task ID (`tsk_...`).") is_blocked: bool | None = Field( default=None, @@ -303,6 +328,18 @@ class BlockerListResponseDataItem(BaseModel): default=None, description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", ) + source_id: str | None = Field( + default=None, + description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", + ) + source_scope: str | None = Field( + default=None, + 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`.", + ) + source_type: str | None = Field( + default=None, + description="Kind of source object (for example `repository`). `null` when the task has no source.", + ) status: str = Field( ..., description='Current status of the task. One of `"open"`, `"in_progress"`, or `"done"`.', @@ -613,6 +650,10 @@ class TaskBlockingResponseDataItem(BaseModel): default=None, description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", ) + epic: str | None = Field( + default=None, + description="Free-form grouping label. `null` when the task is not in an epic.", + ) id: str = Field(..., description="Task ID (`tsk_...`).") is_blocked: bool | None = Field( default=None, @@ -655,6 +696,18 @@ class TaskBlockingResponseDataItem(BaseModel): default=None, description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", ) + source_id: str | None = Field( + default=None, + description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", + ) + source_scope: str | None = Field( + default=None, + 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`.", + ) + source_type: str | None = Field( + default=None, + description="Kind of source object (for example `repository`). `null` when the task has no source.", + ) status: str = Field( ..., description='Current status of the task. One of `"open"`, `"in_progress"`, or `"done"`.', @@ -844,6 +897,10 @@ class TaskSubtasksResponseDataItem(BaseModel): default=None, description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", ) + epic: str | None = Field( + default=None, + description="Free-form grouping label. `null` when the task is not in an epic.", + ) id: str = Field(..., description="Task ID (`tsk_...`).") is_blocked: bool | None = Field( default=None, @@ -886,6 +943,18 @@ class TaskSubtasksResponseDataItem(BaseModel): default=None, description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", ) + source_id: str | None = Field( + default=None, + description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", + ) + source_scope: str | None = Field( + default=None, + 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`.", + ) + source_type: str | None = Field( + default=None, + description="Kind of source object (for example `repository`). `null` when the task has no source.", + ) status: str = Field( ..., description='Current status of the task. One of `"open"`, `"in_progress"`, or `"done"`.', @@ -1194,6 +1263,7 @@ async def create(self, task: str, input: LeaseCreateInput) -> TaskSessionLease: input.harness: Bounded harness identifier. input.lease_duration_seconds: Requested lease lifetime in seconds; the task aggregate enforces its bounds. input.lease_id: Caller-generated lease UUID. + input.require_ready: Conservatively reject the claim when the current task projection has unfinished blockers. input.session_id: Caller-generated coding-session UUID. input.session_name: Human-readable coding-session label. @@ -1231,12 +1301,46 @@ async def renew(self, task: str, input: LeaseRenewInput) -> TaskSessionLease: ) +class AsyncLinkResource: + def __init__(self, http: HttpClient): + self._http = http + + async def remove(self, task: str) -> None: + """ + Remove an external link from a task + + Args: + task: Task ID (`tsk_...`). + + Returns: + HTTP 204 on success. + """ + await self._http.request(f"/api/v1/tasks/{task}/links", method="DELETE") + + async def create(self, task: str, input: LinkCreateInput) -> dict[str, Any]: + """ + Add an external link to a task + + Args: + task: Task ID (`tsk_...`). + input: Request body. + input.external_scope: External container ID. + input.object_id: External object ID. + input.object_type: External object type. + + Returns: + The created external link. + """ + return await self._http.request(f"/api/v1/tasks/{task}/links", method="POST", body=input) + + class AsyncTaskResource: def __init__(self, http: HttpClient): self._http = http self.blockers = AsyncBlockerResource(http) self.comments = AsyncCommentResource(http) self.lease = AsyncLeaseResource(http) + self.links = AsyncLinkResource(http) async def delete(self, task: str) -> None: """ @@ -1319,6 +1423,7 @@ async def replace(self, task: str, input: TaskReplaceInput) -> Task: input.agent: Explicit agent (`agi_...`). It is the owner when `team` and `user` are absent; otherwise it is the acting principal. input.description: Updated long-form description. input.due_date: Updated due date in ISO 8601 format, or null to clear it. + input.epic: Replacement grouping label. Pass null to clear it. input.lease_id: Current caller-held lease UUID. Must be paired with `lease_session_id`. input.lease_session_id: Current coding-session UUID. Must be paired with `lease_id`. input.links: Replacement related-links object. @@ -1329,6 +1434,9 @@ async def replace(self, task: str, input: TaskReplaceInput) -> Task: input.owner_user: Assign to a user by public ID (`usr_...`). input.parent: Move this task under a top-level parent (`tsk_...`), or pass null to promote it to a top-level task. A task that has subtasks cannot become one. input.priority: Updated priority from 0 (highest) to 4 (lowest). + input.source_id: Replacement source object identity. Must be supplied with the other source fields. + input.source_scope: Replacement source container. Pass together with `source_type` and `source_id`, or pass all three as null to clear the source. + input.source_type: Replacement source object kind. Must be supplied with the other source fields. input.status: Updated status: `open`, `in_progress`, or `done`. input.tags: Replacement tag list (max 20, each up to 40 characters; normalized to lowercase). Pass an empty array to clear all tags. input.team: Explicit owning team (`tem_...`) for a developer or server-to-server call. @@ -1758,6 +1866,7 @@ def create(self, task: str, input: LeaseCreateInput) -> TaskSessionLease: input.harness: Bounded harness identifier. input.lease_duration_seconds: Requested lease lifetime in seconds; the task aggregate enforces its bounds. input.lease_id: Caller-generated lease UUID. + input.require_ready: Conservatively reject the claim when the current task projection has unfinished blockers. input.session_id: Caller-generated coding-session UUID. input.session_name: Human-readable coding-session label. @@ -1795,12 +1904,46 @@ def renew(self, task: str, input: LeaseRenewInput) -> TaskSessionLease: ) +class LinkResource: + def __init__(self, http: SyncHttpClient): + self._http = http + + def remove(self, task: str) -> None: + """ + Remove an external link from a task + + Args: + task: Task ID (`tsk_...`). + + Returns: + HTTP 204 on success. + """ + self._http.request(f"/api/v1/tasks/{task}/links", method="DELETE") + + def create(self, task: str, input: LinkCreateInput) -> dict[str, Any]: + """ + Add an external link to a task + + Args: + task: Task ID (`tsk_...`). + input: Request body. + input.external_scope: External container ID. + input.object_id: External object ID. + input.object_type: External object type. + + Returns: + The created external link. + """ + return self._http.request(f"/api/v1/tasks/{task}/links", method="POST", body=input) + + class TaskResource: def __init__(self, http: SyncHttpClient): self._http = http self.blockers = BlockerResource(http) self.comments = CommentResource(http) self.lease = LeaseResource(http) + self.links = LinkResource(http) def delete(self, task: str) -> None: """ @@ -1883,6 +2026,7 @@ def replace(self, task: str, input: TaskReplaceInput) -> Task: input.agent: Explicit agent (`agi_...`). It is the owner when `team` and `user` are absent; otherwise it is the acting principal. input.description: Updated long-form description. input.due_date: Updated due date in ISO 8601 format, or null to clear it. + input.epic: Replacement grouping label. Pass null to clear it. input.lease_id: Current caller-held lease UUID. Must be paired with `lease_session_id`. input.lease_session_id: Current coding-session UUID. Must be paired with `lease_id`. input.links: Replacement related-links object. @@ -1893,6 +2037,9 @@ def replace(self, task: str, input: TaskReplaceInput) -> Task: input.owner_user: Assign to a user by public ID (`usr_...`). input.parent: Move this task under a top-level parent (`tsk_...`), or pass null to promote it to a top-level task. A task that has subtasks cannot become one. input.priority: Updated priority from 0 (highest) to 4 (lowest). + input.source_id: Replacement source object identity. Must be supplied with the other source fields. + input.source_scope: Replacement source container. Pass together with `source_type` and `source_id`, or pass all three as null to clear the source. + input.source_type: Replacement source object kind. Must be supplied with the other source fields. input.status: Updated status: `open`, `in_progress`, or `done`. input.tags: Replacement tag list (max 20, each up to 40 characters; normalized to lowercase). Pass an empty array to clear all tags. input.team: Explicit owning team (`tem_...`) for a developer or server-to-server call. diff --git a/src/archastro/platform/v1/resources/teams.py b/src/archastro/platform/v1/resources/teams.py index 398d0a3..346e851 100644 --- a/src/archastro/platform/v1/resources/teams.py +++ b/src/archastro/platform/v1/resources/teams.py @@ -1,6 +1,6 @@ # Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. # This file is auto-generated by @archastro/sdk-generator. Do not edit. -# Content hash: 17b38b7953d3 +# Content hash: 64601c00bb1d from __future__ import annotations @@ -49,6 +49,8 @@ class TeamTaskCreateInputTask(TypedDict, total=False): "Optional long-form description or notes for the task. Supports plain text." due_date: datetime | None "Date and time by which the task should be completed (ISO 8601). Omit to create the task without a due date." + epic: str | None + "Optional free-form grouping label." links: dict[str, Any] | None "Arbitrary key-value map of named URLs or references associated with the task (e.g. external ticket links)." metadata: dict[str, Any] | None @@ -63,6 +65,12 @@ class TeamTaskCreateInputTask(TypedDict, total=False): "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_id: str | None + "Source object identity (for example `ArchAstro/firstlanding`)." + 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`." + source_type: str | None + "Kind of source object (for example `repository`)." status: str | None 'Initial status for the task. One of `"open"`, `"in_progress"`, or `"done"`. Defaults to `"open"` when omitted.' tags: list[str] | None @@ -102,7 +110,7 @@ class TeamThreadCreateInputThreadProfilePicture(TypedDict, total=False): class TeamThreadCreateInputThreadSettings(TypedDict, total=False): agent_enabled: bool | None - "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." + "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 TeamThreadCreateInputThread(TypedDict, total=False): @@ -114,6 +122,8 @@ class TeamThreadCreateInputThread(TypedDict, total=False): "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: Literal["personal"] | None + "Optional behavioral subtype. `personal` is accepted only for a user-owned thread and limits membership to that user and agents currently owned by them. Mirror kinds remain server-derived and cannot be selected by callers." members: list[TeamThreadCreateInputThreadMembersItem] | 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, Any] | None @@ -520,6 +530,7 @@ class MemberListResponseDataItemAgentSourceSolutionCurrentSolutionTemplatesItemD participants: ( list[ MemberListResponseDataItemAgentSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContractParticipantsItem + | None ] | None ) = Field( @@ -535,14 +546,14 @@ class MemberListResponseDataItemAgentSourceSolutionCurrentSolutionTemplatesItemD class MemberListResponseDataItemAgentSourceSolutionCurrentSolutionTemplatesItemDetails(BaseModel): automation_type: str | None = Field( default=None, - description="Automation execution type (`invoked`, `scheduled`, or `trigger`).", + description="Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", ) invoke_contract: ( MemberListResponseDataItemAgentSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContract | None ) = Field( default=None, - description="Schema-driven payload and participant inputs for an invoked automation. Used by installation clients to collect locked prefills before provisioning.", + 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.", ) type: Literal["automation"] = Field( default="automation", @@ -596,7 +607,7 @@ class MemberListResponseDataItemAgentSourceSolutionCurrentSolution(BaseModel): default=None, description="Category tag keys declared in the Solution body, used to group Solutions in the catalog. An empty array when the body declares none.", ) - created_at: datetime | None = Field( + created_at: str | None = Field( default=None, description="When the Solution config was first imported (ISO 8601)." ) description: str | None = Field( @@ -683,7 +694,7 @@ class MemberListResponseDataItemAgentSourceSolutionCurrentSolution(BaseModel): 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.", ) ) - updated_at: datetime | None = Field( + updated_at: str | None = Field( default=None, description="When the Solution config was last modified (ISO 8601)." ) upgrade_available: bool = Field( @@ -769,6 +780,7 @@ class MemberListResponseDataItemAgentSourceSolutionSolutionTemplatesItemDetailsI participants: ( list[ MemberListResponseDataItemAgentSourceSolutionSolutionTemplatesItemDetailsInvokeContractParticipantsItem + | None ] | None ) = Field( @@ -784,14 +796,14 @@ class MemberListResponseDataItemAgentSourceSolutionSolutionTemplatesItemDetailsI class MemberListResponseDataItemAgentSourceSolutionSolutionTemplatesItemDetails(BaseModel): automation_type: str | None = Field( default=None, - description="Automation execution type (`invoked`, `scheduled`, or `trigger`).", + description="Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", ) invoke_contract: ( MemberListResponseDataItemAgentSourceSolutionSolutionTemplatesItemDetailsInvokeContract | None ) = Field( default=None, - description="Schema-driven payload and participant inputs for an invoked automation. Used by installation clients to collect locked prefills before provisioning.", + 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.", ) type: Literal["automation"] = Field( default="automation", @@ -845,7 +857,7 @@ class MemberListResponseDataItemAgentSourceSolutionSolution(BaseModel): default=None, description="Category tag keys declared in the Solution body, used to group Solutions in the catalog. An empty array when the body declares none.", ) - created_at: datetime | None = Field( + created_at: str | None = Field( default=None, description="When the Solution config was first imported (ISO 8601)." ) description: str | None = Field( @@ -930,7 +942,7 @@ class MemberListResponseDataItemAgentSourceSolutionSolution(BaseModel): ..., 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.", ) - updated_at: datetime | None = Field( + updated_at: str | None = Field( default=None, description="When the Solution config was last modified (ISO 8601)." ) upgrade_available: bool = Field( @@ -999,7 +1011,7 @@ class MemberListResponseDataItemAgent(BaseModel): app: str | None = Field( default=None, description="ID of the application that owns this agent (`dap_...`)." ) - created_at: datetime | None = Field( + created_at: str | None = Field( default=None, description="When the agent was created (ISO 8601)." ) default_model: str | None = Field( @@ -1066,7 +1078,7 @@ class MemberListResponseDataItemAgent(BaseModel): default=None, 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`).", ) - updated_at: datetime | None = Field( + updated_at: str | None = Field( default=None, description="When the agent was last modified (ISO 8601)." ) user: str | None = Field( @@ -1116,6 +1128,26 @@ class MemberListResponseDataItemUser(BaseModel): default=None, description="Display name of the user's app. `null` when the app association was not preloaded by the caller.", ) + created_by_agent_user: str | None = Field( + default=None, + description="Agent user that created this account (`usr_...`). `null` unless an agent created it.", + ) + created_by_developer: str | None = Field( + default=None, + description="Developer account that created this user (`dva_...`). `null` unless created via a developer token.", + ) + created_by_org: str | None = Field( + default=None, + description="Org of the principal that created this user (`org_...`). `null` on legacy rows.", + ) + created_by_team: str | None = Field( + default=None, + description="Team that created this user (`tem_...`). `null` unless created as a team.", + ) + created_by_user: str | None = Field( + default=None, + description="User who created this account (`usr_...`). `null` on self-signup or legacy rows.", + ) email: str | None = Field(default=None, description="Email address of the user.") id: str = Field(..., description="User ID (`usr_...`).") is_system_user: bool | None = Field( @@ -1142,6 +1174,10 @@ class MemberListResponseDataItemUser(BaseModel): default=None, 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.', ) + org_slug: str | None = Field( + default=None, + 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.", + ) sandbox: str | None = Field( default=None, description="ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.", @@ -1356,6 +1392,10 @@ class TeamTaskListResponseDataItem(BaseModel): default=None, description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", ) + epic: str | None = Field( + default=None, + description="Free-form grouping label. `null` when the task is not in an epic.", + ) id: str = Field(..., description="Task ID (`tsk_...`).") is_blocked: bool | None = Field( default=None, @@ -1398,6 +1438,18 @@ class TeamTaskListResponseDataItem(BaseModel): default=None, description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", ) + source_id: str | None = Field( + default=None, + description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", + ) + source_scope: str | None = Field( + default=None, + 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`.", + ) + source_type: str | None = Field( + default=None, + description="Kind of source object (for example `repository`). `null` when the task has no source.", + ) status: str = Field( ..., description='Current status of the task. One of `"open"`, `"in_progress"`, or `"done"`.', @@ -1593,6 +1645,10 @@ class TeamTaskBlockerCyclesResponseDataItemTasksItem(BaseModel): default=None, description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", ) + epic: str | None = Field( + default=None, + description="Free-form grouping label. `null` when the task is not in an epic.", + ) id: str = Field(..., description="Task ID (`tsk_...`).") is_blocked: bool | None = Field( default=None, @@ -1635,6 +1691,18 @@ class TeamTaskBlockerCyclesResponseDataItemTasksItem(BaseModel): default=None, description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", ) + source_id: str | None = Field( + default=None, + description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", + ) + source_scope: str | None = Field( + default=None, + 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`.", + ) + source_type: str | None = Field( + default=None, + description="Kind of source object (for example `repository`). `null` when the task has no source.", + ) status: str = Field( ..., description='Current status of the task. One of `"open"`, `"in_progress"`, or `"done"`.', @@ -1698,6 +1766,270 @@ class TeamTaskMetricsResponse(BaseModel): start_at: datetime +class TeamTaskReadyResponseDataItemTaskCreatedByActorProfilePicture(BaseModel): + file: str | None = Field( + default=None, + description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", + ) + height: int | None = Field( + default=None, description="Height of the image in pixels. `null` if not known." + ) + media: str | None = Field( + default=None, + description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", + ) + mime_type: str | None = Field( + default=None, + description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', + ) + refresh_url: str | None = Field( + default=None, + 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.", + ) + url: str | None = Field( + default=None, + 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.", + ) + width: int | None = Field( + default=None, description="Width of the image in pixels. `null` if not known." + ) + + +class TeamTaskReadyResponseDataItemTaskCreatedByActor(BaseModel): + alias: str | None = Field( + default=None, + description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", + ) + id: str | None = Field( + default=None, + description='Composite actor identifier. Format is `"user-"` for human users or `"agent-"` for agents.', + ) + name: str | None = Field( + default=None, + description="Display name of the actor shown in the UI. `null` if no name is set.", + ) + profile_picture: TeamTaskReadyResponseDataItemTaskCreatedByActorProfilePicture | None = Field( + default=None, + description="Profile picture for the actor. `null` if the actor has no profile picture.", + ) + + +class TeamTaskReadyResponseDataItemTaskCurrentLease(BaseModel): + expires_at: datetime = Field( + ..., description="Server-calculated lease expiry in ISO 8601 format." + ) + harness: str = Field(..., description="Bounded harness identifier for the coding session.") + session_name: str = Field( + ..., description="Display name supplied by the coding session that holds the lease." + ) + + +class TeamTaskReadyResponseDataItemTaskOwnerActorProfilePicture(BaseModel): + file: str | None = Field( + default=None, + description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", + ) + height: int | None = Field( + default=None, description="Height of the image in pixels. `null` if not known." + ) + media: str | None = Field( + default=None, + description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", + ) + mime_type: str | None = Field( + default=None, + description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', + ) + refresh_url: str | None = Field( + default=None, + 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.", + ) + url: str | None = Field( + default=None, + 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.", + ) + width: int | None = Field( + default=None, description="Width of the image in pixels. `null` if not known." + ) + + +class TeamTaskReadyResponseDataItemTaskOwnerActor(BaseModel): + alias: str | None = Field( + default=None, + description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", + ) + id: str | None = Field( + default=None, + description='Composite actor identifier. Format is `"user-"` for human users or `"agent-"` for agents.', + ) + name: str | None = Field( + default=None, + description="Display name of the actor shown in the UI. `null` if no name is set.", + ) + profile_picture: TeamTaskReadyResponseDataItemTaskOwnerActorProfilePicture | None = Field( + default=None, + description="Profile picture for the actor. `null` if the actor has no profile picture.", + ) + + +class TeamTaskReadyResponseDataItemTask(BaseModel): + agent: str | None = Field( + default=None, + description="ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", + ) + blocked_by_count: int | None = Field( + default=None, + description="Number of tasks marked as blocking this task, whether or not they are done (see `GET /tasks/{task}/blockers`). Computed on list/show reads; create/update responses may lag one read behind.", + ) + closed_at: datetime | None = Field( + default=None, + description="When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", + ) + comments_count: int | None = Field( + default=None, description="Total number of comments posted on this task." + ) + created_at: datetime | None = Field( + default=None, description="When the task was created (ISO 8601)." + ) + created_by_actor: TeamTaskReadyResponseDataItemTaskCreatedByActor | None = Field( + default=None, + 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).", + ) + created_by_agent: str | None = Field( + default=None, + 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.", + ) + created_by_user: str | None = Field( + default=None, + 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.", + ) + current_lease: TeamTaskReadyResponseDataItemTaskCurrentLease | None = Field( + default=None, + 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.", + ) + description: str | None = Field( + default=None, + description="Long-form description or notes for the task. `null` if no description has been provided.", + ) + due_date: datetime | None = Field( + default=None, + description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", + ) + epic: str | None = Field( + default=None, + description="Free-form grouping label. `null` when the task is not in an epic.", + ) + id: str = Field(..., description="Task ID (`tsk_...`).") + is_blocked: bool | None = Field( + default=None, + description="`true` while at least one blocking task is not yet done. Informational only a blocked task can still change status and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on list/show reads; create/update responses report `false` until the next read.", + ) + links: dict[str, Any] | None = Field( + default=None, + description="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, Any] | None = Field( + default=None, + description="Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.", + ) + name: str = Field(..., description="Human-readable title of the task.") + org: str | None = Field( + default=None, + description="ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", + ) + owner_actor: TeamTaskReadyResponseDataItemTaskOwnerActor | None = Field( + default=None, + 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).", + ) + owner_agent: str | None = Field( + default=None, + 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.", + ) + owner_user: str | None = Field( + default=None, + 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.", + ) + parent: str | None = Field( + default=None, + description="ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks. Subtasks nest exactly one level.", + ) + priority: int | None = Field( + default=None, + description="Priority level of the task from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when not explicitly set.", + ) + sandbox: str | None = Field( + default=None, + description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", + ) + source_id: str | None = Field( + default=None, + description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", + ) + source_scope: str | None = Field( + default=None, + 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`.", + ) + source_type: str | None = Field( + default=None, + description="Kind of source object (for example `repository`). `null` when the task has no source.", + ) + status: str = Field( + ..., + description='Current status of the task. One of `"open"`, `"in_progress"`, or `"done"`.', + ) + subtasks_count: int | None = Field( + default=None, + description="Number of subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.", + ) + tags: list[str] | None = Field( + default=None, + description="Labels for grouping and filtering, stored lowercase and de-duplicated. Empty array when untagged.", + ) + team: str | None = Field( + default=None, + description="ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", + ) + thread: str | None = Field( + default=None, + 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.", + ) + updated_at: datetime | None = Field( + default=None, description="When the task was last modified (ISO 8601)." + ) + user: str | None = Field( + default=None, + description="ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", + ) + + +class TeamTaskReadyResponseDataItem(BaseModel): + readiness: Literal["ready", "blocked", "leased"] = Field( + ..., description="One of `ready`, `blocked`, or `leased`." + ) + reason: Literal["open_blockers", "active_lease"] | None = Field( + default=None, + description="Stable exclusion reason: `open_blockers` or `active_lease`; omitted when ready.", + ) + task: TeamTaskReadyResponseDataItemTask = Field( + ..., description="The task evaluated for readiness." + ) + + +class TeamTaskReadyResponse(BaseModel): + """ + Successful response + """ + + after_cursor: str | None = None + authoritative: bool = Field( + ..., + description="Always false because projections can lag writes and a later claim can race this read.", + ) + before_cursor: str | None = None + data: list[TeamTaskReadyResponseDataItem] + has_more: bool + + class TeamTaskSearchResponseDataItemCreatedByActorProfilePicture(BaseModel): file: str | None = Field( default=None, @@ -1847,6 +2179,10 @@ class TeamTaskSearchResponseDataItem(BaseModel): default=None, description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", ) + epic: str | None = Field( + default=None, + description="Free-form grouping label. `null` when the task is not in an epic.", + ) id: str = Field(..., description="Task ID (`tsk_...`).") is_blocked: bool | None = Field( default=None, @@ -1889,6 +2225,18 @@ class TeamTaskSearchResponseDataItem(BaseModel): default=None, description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", ) + source_id: str | None = Field( + default=None, + description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", + ) + source_scope: str | None = Field( + default=None, + 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`.", + ) + source_type: str | None = Field( + default=None, + description="Kind of source object (for example `repository`). `null` when the task has no source.", + ) status: str = Field( ..., description='Current status of the task. One of `"open"`, `"in_progress"`, or `"done"`.', @@ -2176,7 +2524,7 @@ class TeamThreadListResponseDataItemParentMessageAttachmentsItem(BaseModel): ) media_type: str | None = Field( default=None, - description='The media category, e.g. `"video"` or `"audio"`. Present on `media` type only. `null` otherwise.', + description='The media category, e.g. `"video"` or `"audio"`. Present on `media` type only; omitted otherwise.', ) name: str | None = Field( default=None, @@ -2184,7 +2532,7 @@ class TeamThreadListResponseDataItemParentMessageAttachmentsItem(BaseModel): ) object: dict[str, Any] | None = Field( default=None, - 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`. `null` on other types.", + description="The full embedded object payload. For `task` type, contains the task record. For `action` type, contains the action definition. For `chart` type, contains the chart with its inline `spec`. Omitted on other types.", ) title: str | None = Field( default=None, @@ -2202,7 +2550,7 @@ class TeamThreadListResponseDataItemParentMessageAttachmentsItem(BaseModel): list[TeamThreadListResponseDataItemParentMessageAttachmentsItemVariantsItem] | None ) = Field( default=None, - description="Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only. `null` otherwise.", + description="Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only; omitted otherwise.", ) version: int | None = Field( default=None, @@ -2257,7 +2605,7 @@ class TeamThreadListResponseDataItemParentMessage(BaseModel): default=None, description="Text content of the message. `null` for messages that contain only attachments.", ) - created_at: datetime | None = Field( + created_at: str | None = Field( default=None, description="When the message was posted (ISO 8601)." ) has_replies: bool | None = Field( @@ -2325,14 +2673,13 @@ class TeamThreadListResponseDataItemParentMessage(BaseModel): description="ID of the team this message is scoped to (`tem_...`). `null` if the message is not team-scoped.", ) thread: str | None = Field( - default=None, - description="ID of the thread this message belongs to (`thr_...`). `null` for messages not yet associated with a thread.", + default=None, description="ID of the thread this message belongs to (`thr_...`)." ) type: str | None = Field( default=None, 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.", ) - user: str | None = Field( + user: str | dict[str, Any] | None = Field( default=None, 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.", ) @@ -2354,6 +2701,26 @@ class TeamThreadListResponseDataItemParticipantsItem(BaseModel): default=None, description="Display name of the user's app. `null` when the app association was not preloaded by the caller.", ) + created_by_agent_user: str | None = Field( + default=None, + description="Agent user that created this account (`usr_...`). `null` unless an agent created it.", + ) + created_by_developer: str | None = Field( + default=None, + description="Developer account that created this user (`dva_...`). `null` unless created via a developer token.", + ) + created_by_org: str | None = Field( + default=None, + description="Org of the principal that created this user (`org_...`). `null` on legacy rows.", + ) + created_by_team: str | None = Field( + default=None, + description="Team that created this user (`tem_...`). `null` unless created as a team.", + ) + created_by_user: str | None = Field( + default=None, + description="User who created this account (`usr_...`). `null` on self-signup or legacy rows.", + ) email: str | None = Field(default=None, description="Email address of the user.") id: str = Field(..., description="User ID (`usr_...`).") is_system_user: bool | None = Field( @@ -2380,6 +2747,10 @@ class TeamThreadListResponseDataItemParticipantsItem(BaseModel): default=None, 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.', ) + org_slug: str | None = Field( + default=None, + 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.", + ) sandbox: str | None = Field( default=None, description="ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.", @@ -2521,6 +2892,7 @@ class TeamThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrent participants: ( list[ TeamThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContractParticipantsItem + | None ] | None ) = Field( @@ -2538,14 +2910,14 @@ class TeamThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrent ): automation_type: str | None = Field( default=None, - description="Automation execution type (`invoked`, `scheduled`, or `trigger`).", + description="Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", ) invoke_contract: ( TeamThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContract | None ) = Field( default=None, - description="Schema-driven payload and participant inputs for an invoked automation. Used by installation clients to collect locked prefills before provisioning.", + 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.", ) type: Literal["automation"] = Field( default="automation", @@ -2602,7 +2974,7 @@ class TeamThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrent default=None, description="Category tag keys declared in the Solution body, used to group Solutions in the catalog. An empty array when the body declares none.", ) - created_at: datetime | None = Field( + created_at: str | None = Field( default=None, description="When the Solution config was first imported (ISO 8601)." ) description: str | None = Field( @@ -2692,7 +3064,7 @@ class TeamThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrent ..., 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.", ) - updated_at: datetime | None = Field( + updated_at: str | None = Field( default=None, description="When the Solution config was last modified (ISO 8601)." ) upgrade_available: bool = Field( @@ -2778,6 +3150,7 @@ class TeamThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutio participants: ( list[ TeamThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContractParticipantsItem + | None ] | None ) = Field( @@ -2795,14 +3168,14 @@ class TeamThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutio ): automation_type: str | None = Field( default=None, - description="Automation execution type (`invoked`, `scheduled`, or `trigger`).", + description="Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", ) invoke_contract: ( TeamThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContract | None ) = Field( default=None, - description="Schema-driven payload and participant inputs for an invoked automation. Used by installation clients to collect locked prefills before provisioning.", + 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.", ) type: Literal["automation"] = Field( default="automation", @@ -2859,7 +3232,7 @@ class TeamThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutio default=None, description="Category tag keys declared in the Solution body, used to group Solutions in the catalog. An empty array when the body declares none.", ) - created_at: datetime | None = Field( + created_at: str | None = Field( default=None, description="When the Solution config was first imported (ISO 8601)." ) description: str | None = Field( @@ -2948,7 +3321,7 @@ class TeamThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutio ..., 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.", ) - updated_at: datetime | None = Field( + updated_at: str | None = Field( default=None, description="When the Solution config was last modified (ISO 8601)." ) upgrade_available: bool = Field( @@ -3019,7 +3392,7 @@ class TeamThreadListResponseDataItemParticipatingAgentsItem(BaseModel): app: str | None = Field( default=None, description="ID of the application that owns this agent (`dap_...`)." ) - created_at: datetime | None = Field( + created_at: str | None = Field( default=None, description="When the agent was created (ISO 8601)." ) default_model: str | None = Field( @@ -3088,7 +3461,7 @@ class TeamThreadListResponseDataItemParticipatingAgentsItem(BaseModel): default=None, 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`).", ) - updated_at: datetime | None = Field( + updated_at: str | None = Field( default=None, description="When the agent was last modified (ISO 8601)." ) user: str | None = Field( @@ -3100,7 +3473,7 @@ class TeamThreadListResponseDataItemParticipatingAgentsItem(BaseModel): class TeamThreadListResponseDataItemSettings(BaseModel): agent_enabled: bool | None = Field( default=None, - 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.", + 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.", ) @@ -3109,7 +3482,7 @@ class TeamThreadListResponseDataItem(BaseModel): default=None, description="ID of the agent that owns this thread (`agt_...`). `null` for user-owned or team-owned threads.", ) - created_at: datetime | None = Field( + created_at: str | None = Field( default=None, description="When the thread was created (ISO 8601)." ) creator: str | dict[str, Any] | None = Field( @@ -3143,9 +3516,9 @@ class TeamThreadListResponseDataItem(BaseModel): ) kind: str | None = Field( default=None, - description='Thread subtype: `"standard"` for ordinary threads, `"slack_mirror"` for the membership-strict mirror of a Slack channel, `"slashwork_mirror"` for the membership-strict mirror of a Slashwork group. Read-only derived server-side at creation, never accepted from params.', + description='Thread subtype: `"standard"` for ordinary threads, `"personal"` for a user-and-owned-agents roster, `"slack_mirror"` for the membership-strict mirror of a Slack channel, or `"slashwork_mirror"` for the membership-strict mirror of a Slashwork group. `personal` is an explicit user-thread creation option; mirror kinds are server-derived.', ) - last_activity: datetime | None = Field( + last_activity: str | None = Field( default=None, 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.", ) @@ -3185,11 +3558,11 @@ class TeamThreadListResponseDataItem(BaseModel): default=None, description="Composite actor identifiers for all participants currently active in this thread. Present only when actor enrichment is requested.", ) - participating_agents: list[TeamThreadListResponseDataItemParticipatingAgentsItem] | None = ( - Field( - default=None, - description="Expanded agent objects for all agents participating in this thread. Present only when agent enrichment is requested.", - ) + participating_agents: ( + list[TeamThreadListResponseDataItemParticipatingAgentsItem | None] | None + ) = Field( + default=None, + description="Expanded agent objects for all agents participating in this thread. Present only when agent enrichment is requested.", ) role: str | None = Field( default=None, @@ -3207,7 +3580,7 @@ class TeamThreadListResponseDataItem(BaseModel): default=None, description="URL-safe slug for the thread, used in human-readable permalinks. `null` if not assigned.", ) - sub_threads: list[dict[str, Any]] | None = Field( + sub_threads: list[dict[str, Any] | None] | None = Field( default=None, description="Threads that are nested under this thread as replies to a parent message. Present only when sub-thread enrichment is requested.", ) @@ -3223,15 +3596,15 @@ class TeamThreadListResponseDataItem(BaseModel): default=None, description="Human-readable name of the thread. `null` if no title has been set.", ) - ttl: int | None = Field( + ttl: str | None = Field( default=None, - description="Time-to-live in seconds after which the thread may be automatically cleaned up. `null` if the thread does not expire.", + description="Offset-free expiry timestamp after which the thread may be automatically cleaned up. `null` if the thread does not expire.", ) unread_count: int | None = Field( default=None, description="Number of messages in this thread that the authenticated user has not yet read. Present only when read-state enrichment is requested.", ) - updated_at: datetime | None = Field( + updated_at: str | None = Field( default=None, description="When the thread was last modified (ISO 8601)." ) user: str | None = Field( @@ -3713,7 +4086,10 @@ async def create(self, team: str, input: MemberCreateInput) -> TeamMembership: Adds a user or agent as a member of the specified team and returns the new membership with HTTP 201. Provide exactly one of `user` or `agent` supplying both or neither returns a 400 error. - The caller must have permission to manage the team. When an `app` is provided, + Adding a user requires permission to manage the team (team owner, team + admin, or org admin). Adding an agent with the default `"member"` role is + also open to any existing member of the team; assigning an elevated role to + an agent still requires team-manage permission. When an `app` is provided, the request is scoped to that app and the caller must hold a valid app-scoped token. The default role is `"member"` when `role` is omitted. @@ -3780,12 +4156,17 @@ async def list( priority: int | None = None, tag: str | None = None, parent: str | None = None, + source_scope: str | None = None, + source_type: str | None = None, + source_id: str | None = None, + epic: str | None = None, search: str | None = None, sort: str | None = None, order: str | None = None, due_before: str | None = None, due_after: str | None = None, overdue: bool | None = None, + ready: bool | None = None, limit: int | None = None, after_cursor: str | None = None, ) -> TeamTaskListResponse: @@ -3810,12 +4191,17 @@ async def list( 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 pass `none` to return only top-level tasks. + source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_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"` for `created` and `"asc"` for `due_date` and `priority`. due_before: Return only tasks with a due date strictly before this ISO 8601 datetime (`2026-08-01T00:00:00Z`) or date (`2026-08-01`, meaning midnight UTC). Tasks without a due date are excluded. due_after: Return only tasks with a due date strictly after this ISO 8601 datetime or date. Tasks without a due date are excluded. overdue: When `true`, return only overdue tasks: a due date before the current UTC day and a status other than `"done"`. A task due today is not overdue. + ready: When true, return only open tasks with no unfinished blockers and no active session lease. This is a projection snapshot; claim a lease before starting work. limit: Maximum number of tasks to return. Capped at 100. after_cursor: Opaque cursor returned by the previous page. @@ -3839,6 +4225,14 @@ async def list( query["tag"] = tag if parent is not None: query["parent"] = parent + if source_scope is not None: + query["source_scope"] = source_scope + if source_type is not None: + query["source_type"] = source_type + if source_id is not None: + query["source_id"] = source_id + if epic is not None: + query["epic"] = epic if search is not None: query["search"] = search if sort is not None: @@ -3851,6 +4245,8 @@ async def list( query["due_after"] = due_after if overdue is not None: query["overdue"] = overdue + if ready is not None: + query["ready"] = ready if limit is not None: query["limit"] = limit if after_cursor is not None: @@ -3962,6 +4358,71 @@ async def metrics(self, team: str, *, days: int | None = None) -> TeamTaskMetric response_type=TeamTaskMetricsResponse, ) + async def ready( + self, + team: str, + *, + user: 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, + ) -> TeamTaskReadyResponse: + """ + List an owner's ready tasks + Returns open tasks with no unfinished blockers and no active session lease. + Readiness is calculated by the server from the current task projection. It is + a snapshot, not a reservation; claim a task lease before starting work. + Pass `explain=true` to include every open task with a stable readiness reason. + + Args: + team: Team ID (`tem_...`). Only tasks belonging to this team are returned. + user: User ID (`usr_...`) 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_type` and `source_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 + """ + query: dict[str, object] = {} + if user is not None: + query["user"] = user + if org is not None: + query["org"] = org + if explain is not None: + query["explain"] = explain + if assigned_to_me is not None: + query["assigned_to_me"] = assigned_to_me + if source_scope is not None: + query["source_scope"] = source_scope + if source_type is not None: + query["source_type"] = source_type + if source_id is not None: + query["source_id"] = source_id + if epic is not None: + query["epic"] = epic + if limit is not None: + query["limit"] = limit + if after_cursor is not None: + query["after_cursor"] = after_cursor + return await self._http.request( + f"/api/v1/teams/{team}/tasks/ready", + query=query, + response_type=TeamTaskReadyResponse, + ) + async def search( self, team: str, @@ -3976,6 +4437,10 @@ async def search( 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, ) -> TeamTaskSearchResponse: @@ -4002,6 +4467,10 @@ async def search( 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 pass `none` to return only top-level tasks. + source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_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. @@ -4029,6 +4498,14 @@ async def search( query["tag"] = tag if parent is not None: query["parent"] = parent + if source_scope is not None: + query["source_scope"] = source_scope + if source_type is not None: + query["source_type"] = source_type + if source_id is not None: + query["source_id"] = source_id + if epic is not None: + query["epic"] = epic if limit is not None: query["limit"] = limit if after_cursor is not None: @@ -4594,7 +5071,10 @@ def create(self, team: str, input: MemberCreateInput) -> TeamMembership: Adds a user or agent as a member of the specified team and returns the new membership with HTTP 201. Provide exactly one of `user` or `agent` supplying both or neither returns a 400 error. - The caller must have permission to manage the team. When an `app` is provided, + Adding a user requires permission to manage the team (team owner, team + admin, or org admin). Adding an agent with the default `"member"` role is + also open to any existing member of the team; assigning an elevated role to + an agent still requires team-manage permission. When an `app` is provided, the request is scoped to that app and the caller must hold a valid app-scoped token. The default role is `"member"` when `role` is omitted. @@ -4661,12 +5141,17 @@ def list( priority: int | None = None, tag: str | None = None, parent: str | None = None, + source_scope: str | None = None, + source_type: str | None = None, + source_id: str | None = None, + epic: str | None = None, search: str | None = None, sort: str | None = None, order: str | None = None, due_before: str | None = None, due_after: str | None = None, overdue: bool | None = None, + ready: bool | None = None, limit: int | None = None, after_cursor: str | None = None, ) -> TeamTaskListResponse: @@ -4691,12 +5176,17 @@ def list( 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 pass `none` to return only top-level tasks. + source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_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"` for `created` and `"asc"` for `due_date` and `priority`. due_before: Return only tasks with a due date strictly before this ISO 8601 datetime (`2026-08-01T00:00:00Z`) or date (`2026-08-01`, meaning midnight UTC). Tasks without a due date are excluded. due_after: Return only tasks with a due date strictly after this ISO 8601 datetime or date. Tasks without a due date are excluded. overdue: When `true`, return only overdue tasks: a due date before the current UTC day and a status other than `"done"`. A task due today is not overdue. + ready: When true, return only open tasks with no unfinished blockers and no active session lease. This is a projection snapshot; claim a lease before starting work. limit: Maximum number of tasks to return. Capped at 100. after_cursor: Opaque cursor returned by the previous page. @@ -4720,6 +5210,14 @@ def list( query["tag"] = tag if parent is not None: query["parent"] = parent + if source_scope is not None: + query["source_scope"] = source_scope + if source_type is not None: + query["source_type"] = source_type + if source_id is not None: + query["source_id"] = source_id + if epic is not None: + query["epic"] = epic if search is not None: query["search"] = search if sort is not None: @@ -4732,6 +5230,8 @@ def list( query["due_after"] = due_after if overdue is not None: query["overdue"] = overdue + if ready is not None: + query["ready"] = ready if limit is not None: query["limit"] = limit if after_cursor is not None: @@ -4843,6 +5343,71 @@ def metrics(self, team: str, *, days: int | None = None) -> TeamTaskMetricsRespo response_type=TeamTaskMetricsResponse, ) + def ready( + self, + team: str, + *, + user: 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, + ) -> TeamTaskReadyResponse: + """ + List an owner's ready tasks + Returns open tasks with no unfinished blockers and no active session lease. + Readiness is calculated by the server from the current task projection. It is + a snapshot, not a reservation; claim a task lease before starting work. + Pass `explain=true` to include every open task with a stable readiness reason. + + Args: + team: Team ID (`tem_...`). Only tasks belonging to this team are returned. + user: User ID (`usr_...`) 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_type` and `source_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 + """ + query: dict[str, object] = {} + if user is not None: + query["user"] = user + if org is not None: + query["org"] = org + if explain is not None: + query["explain"] = explain + if assigned_to_me is not None: + query["assigned_to_me"] = assigned_to_me + if source_scope is not None: + query["source_scope"] = source_scope + if source_type is not None: + query["source_type"] = source_type + if source_id is not None: + query["source_id"] = source_id + if epic is not None: + query["epic"] = epic + if limit is not None: + query["limit"] = limit + if after_cursor is not None: + query["after_cursor"] = after_cursor + return self._http.request( + f"/api/v1/teams/{team}/tasks/ready", + query=query, + response_type=TeamTaskReadyResponse, + ) + def search( self, team: str, @@ -4857,6 +5422,10 @@ def search( 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, ) -> TeamTaskSearchResponse: @@ -4883,6 +5452,10 @@ def search( 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 pass `none` to return only top-level tasks. + source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_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. @@ -4910,6 +5483,14 @@ def search( query["tag"] = tag if parent is not None: query["parent"] = parent + if source_scope is not None: + query["source_scope"] = source_scope + if source_type is not None: + query["source_type"] = source_type + if source_id is not None: + query["source_id"] = source_id + if epic is not None: + query["epic"] = epic if limit is not None: query["limit"] = limit if after_cursor is not None: diff --git a/src/archastro/platform/v1/resources/threads.py b/src/archastro/platform/v1/resources/threads.py index 4c1d99d..989245d 100644 --- a/src/archastro/platform/v1/resources/threads.py +++ b/src/archastro/platform/v1/resources/threads.py @@ -1,6 +1,6 @@ # Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. # This file is auto-generated by @archastro/sdk-generator. Do not edit. -# Content hash: d411cee2550f +# Content hash: 630f9d2993fd from __future__ import annotations @@ -543,7 +543,7 @@ class ThreadMessagesResponseDataMessagesItemAttachmentsItem(BaseModel): ) media_type: str | None = Field( default=None, - description='The media category, e.g. `"video"` or `"audio"`. Present on `media` type only. `null` otherwise.', + description='The media category, e.g. `"video"` or `"audio"`. Present on `media` type only; omitted otherwise.', ) name: str | None = Field( default=None, @@ -551,7 +551,7 @@ class ThreadMessagesResponseDataMessagesItemAttachmentsItem(BaseModel): ) object: dict[str, Any] | None = Field( default=None, - 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`. `null` on other types.", + description="The full embedded object payload. For `task` type, contains the task record. For `action` type, contains the action definition. For `chart` type, contains the chart with its inline `spec`. Omitted on other types.", ) title: str | None = Field( default=None, @@ -568,7 +568,7 @@ class ThreadMessagesResponseDataMessagesItemAttachmentsItem(BaseModel): variants: list[ThreadMessagesResponseDataMessagesItemAttachmentsItemVariantsItem] | None = ( Field( default=None, - description="Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only. `null` otherwise.", + description="Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only; omitted otherwise.", ) ) version: int | None = Field( @@ -624,7 +624,7 @@ class ThreadMessagesResponseDataMessagesItem(BaseModel): default=None, description="Text content of the message. `null` for messages that contain only attachments.", ) - created_at: datetime | None = Field( + created_at: str | None = Field( default=None, description="When the message was posted (ISO 8601)." ) has_replies: bool | None = Field( @@ -692,14 +692,13 @@ class ThreadMessagesResponseDataMessagesItem(BaseModel): description="ID of the team this message is scoped to (`tem_...`). `null` if the message is not team-scoped.", ) thread: str | None = Field( - default=None, - description="ID of the thread this message belongs to (`thr_...`). `null` for messages not yet associated with a thread.", + default=None, description="ID of the thread this message belongs to (`thr_...`)." ) type: str | None = Field( default=None, 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.", ) - user: str | None = Field( + user: str | dict[str, Any] | None = Field( default=None, 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.", ) @@ -786,7 +785,7 @@ class ThreadTrajectoriesResponseDataItem(BaseModel): default=None, description="ID of the agent-authored reply message (`msg_...`). `null` if the trajectory has not yet produced a response message.", ) - created_at: datetime | None = Field( + created_at: str | None = Field( default=None, description="When this trajectory link was created (ISO 8601)." ) id: str = Field(..., description="Thread message trajectory ID (`tmt_...`).") @@ -804,7 +803,7 @@ class ThreadTrajectoriesResponseDataItem(BaseModel): default=None, description="ID of the AI trajectory record that captures the full model interaction for this exchange (`trj_...`).", ) - updated_at: datetime | None = Field( + updated_at: str | None = Field( default=None, description="When this trajectory link was last modified (ISO 8601)." ) user_message: str | None = Field( @@ -1382,7 +1381,8 @@ async def trajectories( and `after_cursor` to navigate pages; provide at most one cursor per request. Optionally filter results to trajectories produced in response to a specific message by supplying the `message` parameter. When no trajectories match the query, `data` - is an empty array and both cursor fields are `null`. + is an empty array and both cursor fields are `null`. A cursor that cannot be decoded + returns a 400 `invalid_cursor` error. Args: thread: Thread ID (`thr_...`). The authenticated user must own this thread or belong to its workspace. @@ -1960,7 +1960,8 @@ def trajectories( and `after_cursor` to navigate pages; provide at most one cursor per request. Optionally filter results to trajectories produced in response to a specific message by supplying the `message` parameter. When no trajectories match the query, `data` - is an empty array and both cursor fields are `null`. + is an empty array and both cursor fields are `null`. A cursor that cannot be decoded + returns a 400 `invalid_cursor` error. Args: thread: Thread ID (`thr_...`). The authenticated user must own this thread or belong to its workspace. diff --git a/src/archastro/platform/v1/resources/users.py b/src/archastro/platform/v1/resources/users.py index 9bbbf6d..9508a99 100644 --- a/src/archastro/platform/v1/resources/users.py +++ b/src/archastro/platform/v1/resources/users.py @@ -1,6 +1,6 @@ # Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. # This file is auto-generated by @archastro/sdk-generator. Do not edit. -# Content hash: 9c4b1d511908 +# Content hash: 76fffb92dd91 from __future__ import annotations @@ -11,6 +11,7 @@ from pydantic import BaseModel, Field from ...runtime.http_client import HttpClient, SyncHttpClient +from ...types.system import SystemAccessToken from ...types.tasks import Task from ...types.threads import Thread from ...types.users import User, UserInvite @@ -21,6 +22,8 @@ class UserTaskCreateInputTask(TypedDict, total=False): "Optional long-form description or notes for the task. Supports plain text." due_date: datetime | None "Date and time by which the task should be completed (ISO 8601). Omit to create the task without a due date." + epic: str | None + "Optional free-form grouping label." links: dict[str, Any] | None "Arbitrary key-value map of named URLs or references associated with the task (e.g. external ticket links)." metadata: dict[str, Any] | None @@ -35,6 +38,12 @@ class UserTaskCreateInputTask(TypedDict, total=False): "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_id: str | None + "Source object identity (for example `ArchAstro/firstlanding`)." + 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`." + source_type: str | None + "Kind of source object (for example `repository`)." status: str | None 'Initial status for the task. One of `"open"`, `"in_progress"`, or `"done"`. Defaults to `"open"` when omitted.' tags: list[str] | None @@ -74,7 +83,7 @@ class UserThreadCreateInputThreadProfilePicture(TypedDict, total=False): class UserThreadCreateInputThreadSettings(TypedDict, total=False): agent_enabled: bool | None - "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." + "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(TypedDict, total=False): @@ -86,6 +95,8 @@ class UserThreadCreateInputThread(TypedDict, total=False): "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: Literal["personal"] | None + "Optional behavioral subtype. `personal` is accepted only for a user-owned thread and limits membership to that user and agents currently owned by them. Mirror kinds remain server-derived and cannot be selected by callers." members: list[UserThreadCreateInputThreadMembersItem] | None "Users and agents to add atomically when the thread is created. Each target must pass the same authorization rules as a post-creation member add. Slack mirror threads reject non-empty caller-supplied rosters because their membership is sync-owned." metadata: dict[str, Any] | None @@ -115,6 +126,17 @@ class UserThreadCreateInput(TypedDict, total=False): "Attributes for the new thread. See ThreadCreateParams for the full set of accepted fields." +class TokenCreateInput(TypedDict, total=False): + "Create a personal access token" + + expires_in_days: int | None + "Lifetime in days. One of `7`, `30`, `60`, `90`, or `365`. Defaults to `30`." + name: str | None + 'Human-readable label for the token (e.g. `"Codex MCP"`). Stored as metadata only.' + scopes: list[str] | None + "Optional OAuth scopes to stamp on the token. Omit for `full_access`." + + class UserInvitesInputInvite(TypedDict, total=False): metadata: dict[str, Any] | None "Arbitrary key-value metadata to attach to the invite. Returned as-is on the resulting invite object." @@ -302,6 +324,10 @@ class UserTaskListResponseDataItem(BaseModel): default=None, description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", ) + epic: str | None = Field( + default=None, + description="Free-form grouping label. `null` when the task is not in an epic.", + ) id: str = Field(..., description="Task ID (`tsk_...`).") is_blocked: bool | None = Field( default=None, @@ -344,6 +370,18 @@ class UserTaskListResponseDataItem(BaseModel): default=None, description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", ) + source_id: str | None = Field( + default=None, + description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", + ) + source_scope: str | None = Field( + default=None, + 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`.", + ) + source_type: str | None = Field( + default=None, + description="Kind of source object (for example `repository`). `null` when the task has no source.", + ) status: str = Field( ..., description='Current status of the task. One of `"open"`, `"in_progress"`, or `"done"`.', @@ -539,6 +577,10 @@ class UserTaskBlockerCyclesResponseDataItemTasksItem(BaseModel): default=None, description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", ) + epic: str | None = Field( + default=None, + description="Free-form grouping label. `null` when the task is not in an epic.", + ) id: str = Field(..., description="Task ID (`tsk_...`).") is_blocked: bool | None = Field( default=None, @@ -581,6 +623,18 @@ class UserTaskBlockerCyclesResponseDataItemTasksItem(BaseModel): default=None, description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", ) + source_id: str | None = Field( + default=None, + description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", + ) + source_scope: str | None = Field( + default=None, + 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`.", + ) + source_type: str | None = Field( + default=None, + description="Kind of source object (for example `repository`). `null` when the task has no source.", + ) status: str = Field( ..., description='Current status of the task. One of `"open"`, `"in_progress"`, or `"done"`.', @@ -627,6 +681,270 @@ class UserTaskBlockerCyclesResponse(BaseModel): has_more: bool +class UserTaskReadyResponseDataItemTaskCreatedByActorProfilePicture(BaseModel): + file: str | None = Field( + default=None, + description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", + ) + height: int | None = Field( + default=None, description="Height of the image in pixels. `null` if not known." + ) + media: str | None = Field( + default=None, + description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", + ) + mime_type: str | None = Field( + default=None, + description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', + ) + refresh_url: str | None = Field( + default=None, + 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.", + ) + url: str | None = Field( + default=None, + 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.", + ) + width: int | None = Field( + default=None, description="Width of the image in pixels. `null` if not known." + ) + + +class UserTaskReadyResponseDataItemTaskCreatedByActor(BaseModel): + alias: str | None = Field( + default=None, + description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", + ) + id: str | None = Field( + default=None, + description='Composite actor identifier. Format is `"user-"` for human users or `"agent-"` for agents.', + ) + name: str | None = Field( + default=None, + description="Display name of the actor shown in the UI. `null` if no name is set.", + ) + profile_picture: UserTaskReadyResponseDataItemTaskCreatedByActorProfilePicture | None = Field( + default=None, + description="Profile picture for the actor. `null` if the actor has no profile picture.", + ) + + +class UserTaskReadyResponseDataItemTaskCurrentLease(BaseModel): + expires_at: datetime = Field( + ..., description="Server-calculated lease expiry in ISO 8601 format." + ) + harness: str = Field(..., description="Bounded harness identifier for the coding session.") + session_name: str = Field( + ..., description="Display name supplied by the coding session that holds the lease." + ) + + +class UserTaskReadyResponseDataItemTaskOwnerActorProfilePicture(BaseModel): + file: str | None = Field( + default=None, + description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", + ) + height: int | None = Field( + default=None, description="Height of the image in pixels. `null` if not known." + ) + media: str | None = Field( + default=None, + description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", + ) + mime_type: str | None = Field( + default=None, + description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', + ) + refresh_url: str | None = Field( + default=None, + 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.", + ) + url: str | None = Field( + default=None, + 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.", + ) + width: int | None = Field( + default=None, description="Width of the image in pixels. `null` if not known." + ) + + +class UserTaskReadyResponseDataItemTaskOwnerActor(BaseModel): + alias: str | None = Field( + default=None, + description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", + ) + id: str | None = Field( + default=None, + description='Composite actor identifier. Format is `"user-"` for human users or `"agent-"` for agents.', + ) + name: str | None = Field( + default=None, + description="Display name of the actor shown in the UI. `null` if no name is set.", + ) + profile_picture: UserTaskReadyResponseDataItemTaskOwnerActorProfilePicture | None = Field( + default=None, + description="Profile picture for the actor. `null` if the actor has no profile picture.", + ) + + +class UserTaskReadyResponseDataItemTask(BaseModel): + agent: str | None = Field( + default=None, + description="ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", + ) + blocked_by_count: int | None = Field( + default=None, + description="Number of tasks marked as blocking this task, whether or not they are done (see `GET /tasks/{task}/blockers`). Computed on list/show reads; create/update responses may lag one read behind.", + ) + closed_at: datetime | None = Field( + default=None, + description="When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", + ) + comments_count: int | None = Field( + default=None, description="Total number of comments posted on this task." + ) + created_at: datetime | None = Field( + default=None, description="When the task was created (ISO 8601)." + ) + created_by_actor: UserTaskReadyResponseDataItemTaskCreatedByActor | None = Field( + default=None, + 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).", + ) + created_by_agent: str | None = Field( + default=None, + 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.", + ) + created_by_user: str | None = Field( + default=None, + 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.", + ) + current_lease: UserTaskReadyResponseDataItemTaskCurrentLease | None = Field( + default=None, + 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.", + ) + description: str | None = Field( + default=None, + description="Long-form description or notes for the task. `null` if no description has been provided.", + ) + due_date: datetime | None = Field( + default=None, + description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", + ) + epic: str | None = Field( + default=None, + description="Free-form grouping label. `null` when the task is not in an epic.", + ) + id: str = Field(..., description="Task ID (`tsk_...`).") + is_blocked: bool | None = Field( + default=None, + description="`true` while at least one blocking task is not yet done. Informational only a blocked task can still change status and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on list/show reads; create/update responses report `false` until the next read.", + ) + links: dict[str, Any] | None = Field( + default=None, + description="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, Any] | None = Field( + default=None, + description="Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.", + ) + name: str = Field(..., description="Human-readable title of the task.") + org: str | None = Field( + default=None, + description="ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", + ) + owner_actor: UserTaskReadyResponseDataItemTaskOwnerActor | None = Field( + default=None, + 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).", + ) + owner_agent: str | None = Field( + default=None, + 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.", + ) + owner_user: str | None = Field( + default=None, + 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.", + ) + parent: str | None = Field( + default=None, + description="ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks. Subtasks nest exactly one level.", + ) + priority: int | None = Field( + default=None, + description="Priority level of the task from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when not explicitly set.", + ) + sandbox: str | None = Field( + default=None, + description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", + ) + source_id: str | None = Field( + default=None, + description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", + ) + source_scope: str | None = Field( + default=None, + 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`.", + ) + source_type: str | None = Field( + default=None, + description="Kind of source object (for example `repository`). `null` when the task has no source.", + ) + status: str = Field( + ..., + description='Current status of the task. One of `"open"`, `"in_progress"`, or `"done"`.', + ) + subtasks_count: int | None = Field( + default=None, + description="Number of subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.", + ) + tags: list[str] | None = Field( + default=None, + description="Labels for grouping and filtering, stored lowercase and de-duplicated. Empty array when untagged.", + ) + team: str | None = Field( + default=None, + description="ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", + ) + thread: str | None = Field( + default=None, + 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.", + ) + updated_at: datetime | None = Field( + default=None, description="When the task was last modified (ISO 8601)." + ) + user: str | None = Field( + default=None, + description="ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", + ) + + +class UserTaskReadyResponseDataItem(BaseModel): + readiness: Literal["ready", "blocked", "leased"] = Field( + ..., description="One of `ready`, `blocked`, or `leased`." + ) + reason: Literal["open_blockers", "active_lease"] | None = Field( + default=None, + description="Stable exclusion reason: `open_blockers` or `active_lease`; omitted when ready.", + ) + task: UserTaskReadyResponseDataItemTask = Field( + ..., description="The task evaluated for readiness." + ) + + +class UserTaskReadyResponse(BaseModel): + """ + Successful response + """ + + after_cursor: str | None = None + authoritative: bool = Field( + ..., + description="Always false because projections can lag writes and a later claim can race this read.", + ) + before_cursor: str | None = None + data: list[UserTaskReadyResponseDataItem] + has_more: bool + + class UserTaskSearchResponseDataItemCreatedByActorProfilePicture(BaseModel): file: str | None = Field( default=None, @@ -776,6 +1094,10 @@ class UserTaskSearchResponseDataItem(BaseModel): default=None, description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", ) + epic: str | None = Field( + default=None, + description="Free-form grouping label. `null` when the task is not in an epic.", + ) id: str = Field(..., description="Task ID (`tsk_...`).") is_blocked: bool | None = Field( default=None, @@ -818,6 +1140,18 @@ class UserTaskSearchResponseDataItem(BaseModel): default=None, description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", ) + source_id: str | None = Field( + default=None, + description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", + ) + source_scope: str | None = Field( + default=None, + 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`.", + ) + source_type: str | None = Field( + default=None, + description="Kind of source object (for example `repository`). `null` when the task has no source.", + ) status: str = Field( ..., description='Current status of the task. One of `"open"`, `"in_progress"`, or `"done"`.', @@ -1105,7 +1439,7 @@ class UserThreadListResponseDataItemParentMessageAttachmentsItem(BaseModel): ) media_type: str | None = Field( default=None, - description='The media category, e.g. `"video"` or `"audio"`. Present on `media` type only. `null` otherwise.', + description='The media category, e.g. `"video"` or `"audio"`. Present on `media` type only; omitted otherwise.', ) name: str | None = Field( default=None, @@ -1113,7 +1447,7 @@ class UserThreadListResponseDataItemParentMessageAttachmentsItem(BaseModel): ) object: dict[str, Any] | None = Field( default=None, - 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`. `null` on other types.", + description="The full embedded object payload. For `task` type, contains the task record. For `action` type, contains the action definition. For `chart` type, contains the chart with its inline `spec`. Omitted on other types.", ) title: str | None = Field( default=None, @@ -1131,7 +1465,7 @@ class UserThreadListResponseDataItemParentMessageAttachmentsItem(BaseModel): list[UserThreadListResponseDataItemParentMessageAttachmentsItemVariantsItem] | None ) = Field( default=None, - description="Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only. `null` otherwise.", + description="Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only; omitted otherwise.", ) version: int | None = Field( default=None, @@ -1186,7 +1520,7 @@ class UserThreadListResponseDataItemParentMessage(BaseModel): default=None, description="Text content of the message. `null` for messages that contain only attachments.", ) - created_at: datetime | None = Field( + created_at: str | None = Field( default=None, description="When the message was posted (ISO 8601)." ) has_replies: bool | None = Field( @@ -1254,14 +1588,13 @@ class UserThreadListResponseDataItemParentMessage(BaseModel): description="ID of the team this message is scoped to (`tem_...`). `null` if the message is not team-scoped.", ) thread: str | None = Field( - default=None, - description="ID of the thread this message belongs to (`thr_...`). `null` for messages not yet associated with a thread.", + default=None, description="ID of the thread this message belongs to (`thr_...`)." ) type: str | None = Field( default=None, 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.", ) - user: str | None = Field( + user: str | dict[str, Any] | None = Field( default=None, 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.", ) @@ -1283,6 +1616,26 @@ class UserThreadListResponseDataItemParticipantsItem(BaseModel): default=None, description="Display name of the user's app. `null` when the app association was not preloaded by the caller.", ) + created_by_agent_user: str | None = Field( + default=None, + description="Agent user that created this account (`usr_...`). `null` unless an agent created it.", + ) + created_by_developer: str | None = Field( + default=None, + description="Developer account that created this user (`dva_...`). `null` unless created via a developer token.", + ) + created_by_org: str | None = Field( + default=None, + description="Org of the principal that created this user (`org_...`). `null` on legacy rows.", + ) + created_by_team: str | None = Field( + default=None, + description="Team that created this user (`tem_...`). `null` unless created as a team.", + ) + created_by_user: str | None = Field( + default=None, + description="User who created this account (`usr_...`). `null` on self-signup or legacy rows.", + ) email: str | None = Field(default=None, description="Email address of the user.") id: str = Field(..., description="User ID (`usr_...`).") is_system_user: bool | None = Field( @@ -1309,6 +1662,10 @@ class UserThreadListResponseDataItemParticipantsItem(BaseModel): default=None, 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.', ) + org_slug: str | None = Field( + default=None, + 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.", + ) sandbox: str | None = Field( default=None, description="ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.", @@ -1450,6 +1807,7 @@ class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrent participants: ( list[ UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContractParticipantsItem + | None ] | None ) = Field( @@ -1467,14 +1825,14 @@ class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrent ): automation_type: str | None = Field( default=None, - description="Automation execution type (`invoked`, `scheduled`, or `trigger`).", + description="Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", ) invoke_contract: ( UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContract | None ) = Field( default=None, - description="Schema-driven payload and participant inputs for an invoked automation. Used by installation clients to collect locked prefills before provisioning.", + 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.", ) type: Literal["automation"] = Field( default="automation", @@ -1531,7 +1889,7 @@ class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrent default=None, description="Category tag keys declared in the Solution body, used to group Solutions in the catalog. An empty array when the body declares none.", ) - created_at: datetime | None = Field( + created_at: str | None = Field( default=None, description="When the Solution config was first imported (ISO 8601)." ) description: str | None = Field( @@ -1621,7 +1979,7 @@ class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrent ..., 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.", ) - updated_at: datetime | None = Field( + updated_at: str | None = Field( default=None, description="When the Solution config was last modified (ISO 8601)." ) upgrade_available: bool = Field( @@ -1707,6 +2065,7 @@ class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutio participants: ( list[ UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContractParticipantsItem + | None ] | None ) = Field( @@ -1724,14 +2083,14 @@ class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutio ): automation_type: str | None = Field( default=None, - description="Automation execution type (`invoked`, `scheduled`, or `trigger`).", + description="Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", ) invoke_contract: ( UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContract | None ) = Field( default=None, - description="Schema-driven payload and participant inputs for an invoked automation. Used by installation clients to collect locked prefills before provisioning.", + 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.", ) type: Literal["automation"] = Field( default="automation", @@ -1788,7 +2147,7 @@ class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutio default=None, description="Category tag keys declared in the Solution body, used to group Solutions in the catalog. An empty array when the body declares none.", ) - created_at: datetime | None = Field( + created_at: str | None = Field( default=None, description="When the Solution config was first imported (ISO 8601)." ) description: str | None = Field( @@ -1877,7 +2236,7 @@ class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutio ..., 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.", ) - updated_at: datetime | None = Field( + updated_at: str | None = Field( default=None, description="When the Solution config was last modified (ISO 8601)." ) upgrade_available: bool = Field( @@ -1948,7 +2307,7 @@ class UserThreadListResponseDataItemParticipatingAgentsItem(BaseModel): app: str | None = Field( default=None, description="ID of the application that owns this agent (`dap_...`)." ) - created_at: datetime | None = Field( + created_at: str | None = Field( default=None, description="When the agent was created (ISO 8601)." ) default_model: str | None = Field( @@ -2017,7 +2376,7 @@ class UserThreadListResponseDataItemParticipatingAgentsItem(BaseModel): default=None, 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`).", ) - updated_at: datetime | None = Field( + updated_at: str | None = Field( default=None, description="When the agent was last modified (ISO 8601)." ) user: str | None = Field( @@ -2029,7 +2388,7 @@ class UserThreadListResponseDataItemParticipatingAgentsItem(BaseModel): class UserThreadListResponseDataItemSettings(BaseModel): agent_enabled: bool | None = Field( default=None, - 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.", + 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.", ) @@ -2038,7 +2397,7 @@ class UserThreadListResponseDataItem(BaseModel): default=None, description="ID of the agent that owns this thread (`agt_...`). `null` for user-owned or team-owned threads.", ) - created_at: datetime | None = Field( + created_at: str | None = Field( default=None, description="When the thread was created (ISO 8601)." ) creator: str | dict[str, Any] | None = Field( @@ -2072,9 +2431,9 @@ class UserThreadListResponseDataItem(BaseModel): ) kind: str | None = Field( default=None, - description='Thread subtype: `"standard"` for ordinary threads, `"slack_mirror"` for the membership-strict mirror of a Slack channel, `"slashwork_mirror"` for the membership-strict mirror of a Slashwork group. Read-only derived server-side at creation, never accepted from params.', + description='Thread subtype: `"standard"` for ordinary threads, `"personal"` for a user-and-owned-agents roster, `"slack_mirror"` for the membership-strict mirror of a Slack channel, or `"slashwork_mirror"` for the membership-strict mirror of a Slashwork group. `personal` is an explicit user-thread creation option; mirror kinds are server-derived.', ) - last_activity: datetime | None = Field( + last_activity: str | None = Field( default=None, 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.", ) @@ -2114,11 +2473,11 @@ class UserThreadListResponseDataItem(BaseModel): default=None, description="Composite actor identifiers for all participants currently active in this thread. Present only when actor enrichment is requested.", ) - participating_agents: list[UserThreadListResponseDataItemParticipatingAgentsItem] | None = ( - Field( - default=None, - description="Expanded agent objects for all agents participating in this thread. Present only when agent enrichment is requested.", - ) + participating_agents: ( + list[UserThreadListResponseDataItemParticipatingAgentsItem | None] | None + ) = Field( + default=None, + description="Expanded agent objects for all agents participating in this thread. Present only when agent enrichment is requested.", ) role: str | None = Field( default=None, @@ -2136,7 +2495,7 @@ class UserThreadListResponseDataItem(BaseModel): default=None, description="URL-safe slug for the thread, used in human-readable permalinks. `null` if not assigned.", ) - sub_threads: list[dict[str, Any]] | None = Field( + sub_threads: list[dict[str, Any] | None] | None = Field( default=None, description="Threads that are nested under this thread as replies to a parent message. Present only when sub-thread enrichment is requested.", ) @@ -2152,15 +2511,15 @@ class UserThreadListResponseDataItem(BaseModel): default=None, description="Human-readable name of the thread. `null` if no title has been set.", ) - ttl: int | None = Field( + ttl: str | None = Field( default=None, - description="Time-to-live in seconds after which the thread may be automatically cleaned up. `null` if the thread does not expire.", + description="Offset-free expiry timestamp after which the thread may be automatically cleaned up. `null` if the thread does not expire.", ) unread_count: int | None = Field( default=None, description="Number of messages in this thread that the authenticated user has not yet read. Present only when read-state enrichment is requested.", ) - updated_at: datetime | None = Field( + updated_at: str | None = Field( default=None, description="When the thread was last modified (ISO 8601)." ) user: str | None = Field( @@ -2184,6 +2543,67 @@ class UserThreadListResponse(BaseModel): ) +class TokenListResponseDataItem(BaseModel): + created_at: datetime | None = Field( + default=None, description="When this token was created (ISO 8601)." + ) + created_by_agent_user: str | None = Field( + default=None, + description="Agent user that minted this token (`usr_...`). `null` unless an agent minted it.", + ) + created_by_developer: str | None = Field( + default=None, + description="Developer account that minted this token (`dva_...`). `null` unless minted with a developer token.", + ) + created_by_org: str | None = Field( + default=None, + description="Org of the principal that minted this token (`org_...`). `null` on legacy rows.", + ) + created_by_team: str | None = Field( + default=None, + description="Team that minted this token (`tem_...`). `null` unless minted as a team.", + ) + created_by_user: str | None = Field( + default=None, + description="User who minted this token (`usr_...`). Distinct from the token subject. `null` on legacy rows.", + ) + expires_at: datetime | None = Field( + default=None, + description="When the token expires. `null` on legacy rows that predate stored expiry.", + ) + id: str = Field(..., description="Token ID (`sat_...`).") + last_used_at: datetime | None = Field( + default=None, + description="When this token was last used to authenticate a request. `null` if the token has never been used.", + ) + name: str | None = Field( + default=None, + description="Human-readable label assigned to this token at creation time. `null` when no label was supplied.", + ) + revoked_at: datetime | None = Field( + default=None, + description="When this token was revoked. `null` if the token is still active.", + ) + scopes: str | None = Field( + default=None, + description="Space-separated OAuth scopes stamped on the token. `null` on legacy rows; treat as `full_access`.", + ) + token: str | None = Field( + default=None, + description="Raw bearer token string. Present only in the response to the create request; never returned again after that.", + ) + + +class TokenListResponse(BaseModel): + """ + Successful response + """ + + data: list[TokenListResponseDataItem] = Field( + ..., description="Array of access token objects. Raw JWT values are not included." + ) + + class UserArtifactsResponseDataItemImageSource(BaseModel): file: str | None = Field( default=None, @@ -2292,47 +2712,6 @@ class UserArtifactsResponse(BaseModel): ) -class UserOrgsResponseDataItemVendorLogo(BaseModel): - file: str | None = Field( - default=None, - description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", - ) - height: int | None = Field( - default=None, description="Height of the image in pixels. `null` if not known." - ) - media: str | None = Field( - default=None, - description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", - ) - mime_type: str | None = Field( - default=None, - description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', - ) - refresh_url: str | None = Field( - default=None, - 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.", - ) - url: str | None = Field( - default=None, - 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.", - ) - width: int | None = Field( - default=None, description="Width of the image in pixels. `null` if not known." - ) - - -class UserOrgsResponseDataItemVendor(BaseModel): - id: str = Field(..., description="Organization ID of the vendor (`org_...`).") - logo: UserOrgsResponseDataItemVendorLogo | None = Field( - default=None, - description="Logo of the vendor organization. The `url` is a stable, non-expiring capability URL served by the platform (the same mechanism as catalog `org_logo` fields), safe to hold in caches; `refresh_url` is `null`. `null` when the vendor has no logo.", - ) - name: str | None = Field( - default=None, - description="Display name of the vendor organization. `null` if the vendor has not set a name.", - ) - - class UserOrgsResponseDataItem(BaseModel): created_at: datetime | None = Field( default=None, description="When this organization was created (ISO 8601)." @@ -2356,7 +2735,7 @@ class UserOrgsResponseDataItem(BaseModel): ) onboarding_solution_lookup_key: str | None = Field( default=None, - description="Lookup key (`sol-...`) of the Solution that drove this org's customer onboarding, stamped when the org was first linked into a vendor's network via an explore-install. `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.", + 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.", ) onboarding_track: str | None = Field( default=None, @@ -2381,10 +2760,6 @@ class UserOrgsResponseDataItem(BaseModel): updated_at: datetime | None = Field( default=None, description="When this organization was last modified (ISO 8601)." ) - vendor: UserOrgsResponseDataItemVendor | None = Field( - default=None, - description='Branding of the solution vendor whose network this organization belongs to the vendor of the oldest active vendor relationship. Only present for organizations on the `"customer"` onboarding track; `null` for vendor-track organizations (including vendors that later joined another vendor\'s network) and for customers with no active vendor link. Clients use it to co-brand the workspace ("ArchAgents by Acme").', - ) website: str | None = Field( default=None, description="Public website URL for the organization. `null` if not set." ) @@ -2417,12 +2792,17 @@ async def list( priority: int | None = None, tag: str | None = None, parent: str | None = None, + source_scope: str | None = None, + source_type: str | None = None, + source_id: str | None = None, + epic: str | None = None, search: str | None = None, sort: str | None = None, order: str | None = None, due_before: str | None = None, due_after: str | None = None, overdue: bool | None = None, + ready: bool | None = None, limit: int | None = None, after_cursor: str | None = None, ) -> UserTaskListResponse: @@ -2447,12 +2827,17 @@ async def list( 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 pass `none` to return only top-level tasks. + source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_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"` for `created` and `"asc"` for `due_date` and `priority`. due_before: Return only tasks with a due date strictly before this ISO 8601 datetime (`2026-08-01T00:00:00Z`) or date (`2026-08-01`, meaning midnight UTC). Tasks without a due date are excluded. due_after: Return only tasks with a due date strictly after this ISO 8601 datetime or date. Tasks without a due date are excluded. overdue: When `true`, return only overdue tasks: a due date before the current UTC day and a status other than `"done"`. A task due today is not overdue. + ready: When true, return only open tasks with no unfinished blockers and no active session lease. This is a projection snapshot; claim a lease before starting work. limit: Maximum number of tasks to return. Capped at 100. after_cursor: Opaque cursor returned by the previous page. @@ -2476,6 +2861,14 @@ async def list( query["tag"] = tag if parent is not None: query["parent"] = parent + if source_scope is not None: + query["source_scope"] = source_scope + if source_type is not None: + query["source_type"] = source_type + if source_id is not None: + query["source_id"] = source_id + if epic is not None: + query["epic"] = epic if search is not None: query["search"] = search if sort is not None: @@ -2488,6 +2881,8 @@ async def list( query["due_after"] = due_after if overdue is not None: query["overdue"] = overdue + if ready is not None: + query["ready"] = ready if limit is not None: query["limit"] = limit if after_cursor is not None: @@ -2569,6 +2964,71 @@ async def blocker_cycles( response_type=UserTaskBlockerCyclesResponse, ) + 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: + """ + List an owner's ready tasks + Returns open tasks with no unfinished blockers and no active session lease. + Readiness is calculated by the server from the current task projection. It is + a snapshot, not a reservation; claim a task lease before starting work. + Pass `explain=true` to include every open task with a stable readiness reason. + + Args: + 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_type` and `source_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 + """ + query: dict[str, object] = {} + if team is not None: + query["team"] = team + if org is not None: + query["org"] = org + if explain is not None: + query["explain"] = explain + if assigned_to_me is not None: + query["assigned_to_me"] = assigned_to_me + if source_scope is not None: + query["source_scope"] = source_scope + if source_type is not None: + query["source_type"] = source_type + if source_id is not None: + query["source_id"] = source_id + if epic is not None: + query["epic"] = epic + if limit is not None: + query["limit"] = limit + if after_cursor is not None: + query["after_cursor"] = after_cursor + return await self._http.request( + f"/api/v1/users/{user}/tasks/ready", + query=query, + response_type=UserTaskReadyResponse, + ) + async def search( self, user: str, @@ -2583,6 +3043,10 @@ async def search( 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: @@ -2609,6 +3073,10 @@ async def search( 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 pass `none` to return only top-level tasks. + source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_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. @@ -2636,6 +3104,14 @@ async def search( query["tag"] = tag if parent is not None: query["parent"] = parent + if source_scope is not None: + query["source_scope"] = source_scope + if source_type is not None: + query["source_type"] = source_type + if source_id is not None: + query["source_id"] = source_id + if epic is not None: + query["epic"] = epic if limit is not None: query["limit"] = limit if after_cursor is not None: @@ -2716,11 +3192,94 @@ async def create(self, user: str, input: UserThreadCreateInput) -> Thread: ) +class AsyncTokenResource: + def __init__(self, http: HttpClient): + self._http = http + + async def list(self, user: str) -> 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). + + Args: + user: User ID (`usr_...`) or `me` for the authenticated user. + + Returns: + Successful response + """ + return await self._http.request( + f"/api/v1/users/{user}/tokens", + response_type=TokenListResponse, + ) + + async def create(self, user: str, input: TokenCreateInput) -> SystemAccessToken: + """ + 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. + + Args: + user: User ID (`usr_...`) or `me` for the authenticated user. + input: Request body. + input.expires_in_days: Lifetime in days. One of `7`, `30`, `60`, `90`, or `365`. Defaults to `30`. + 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 `token` field contains the raw JWT and is present only in this response it is not stored and cannot be retrieved later. + """ + return await self._http.request( + f"/api/v1/users/{user}/tokens", + method="POST", + body=input, + response_type=SystemAccessToken, + ) + + async def delete(self, user: str, token: str) -> SystemAccessToken: + """ + 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. + + Args: + user: User ID (`usr_...`) or `me` for the authenticated user. + token: Access token ID (`sat_...`). Must belong to the authenticated user. + + Returns: + The revoked access token. The `revoked_at` field is populated with the time of revocation. + """ + return await self._http.request( + f"/api/v1/users/{user}/tokens/{token}", + method="DELETE", + response_type=SystemAccessToken, + ) + + class AsyncUserResource: def __init__(self, http: HttpClient): self._http = http self.tasks = AsyncUserTaskResource(http) self.threads = AsyncUserThreadResource(http) + self.tokens = AsyncTokenResource(http) async def me(self) -> User: """ @@ -2875,12 +3434,17 @@ def list( priority: int | None = None, tag: str | None = None, parent: str | None = None, + source_scope: str | None = None, + source_type: str | None = None, + source_id: str | None = None, + epic: str | None = None, search: str | None = None, sort: str | None = None, order: str | None = None, due_before: str | None = None, due_after: str | None = None, overdue: bool | None = None, + ready: bool | None = None, limit: int | None = None, after_cursor: str | None = None, ) -> UserTaskListResponse: @@ -2905,12 +3469,17 @@ def list( 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 pass `none` to return only top-level tasks. + source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_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"` for `created` and `"asc"` for `due_date` and `priority`. due_before: Return only tasks with a due date strictly before this ISO 8601 datetime (`2026-08-01T00:00:00Z`) or date (`2026-08-01`, meaning midnight UTC). Tasks without a due date are excluded. due_after: Return only tasks with a due date strictly after this ISO 8601 datetime or date. Tasks without a due date are excluded. overdue: When `true`, return only overdue tasks: a due date before the current UTC day and a status other than `"done"`. A task due today is not overdue. + ready: When true, return only open tasks with no unfinished blockers and no active session lease. This is a projection snapshot; claim a lease before starting work. limit: Maximum number of tasks to return. Capped at 100. after_cursor: Opaque cursor returned by the previous page. @@ -2934,6 +3503,14 @@ def list( query["tag"] = tag if parent is not None: query["parent"] = parent + if source_scope is not None: + query["source_scope"] = source_scope + if source_type is not None: + query["source_type"] = source_type + if source_id is not None: + query["source_id"] = source_id + if epic is not None: + query["epic"] = epic if search is not None: query["search"] = search if sort is not None: @@ -2946,6 +3523,8 @@ def list( query["due_after"] = due_after if overdue is not None: query["overdue"] = overdue + if ready is not None: + query["ready"] = ready if limit is not None: query["limit"] = limit if after_cursor is not None: @@ -3027,6 +3606,71 @@ def blocker_cycles( response_type=UserTaskBlockerCyclesResponse, ) + 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: + """ + List an owner's ready tasks + Returns open tasks with no unfinished blockers and no active session lease. + Readiness is calculated by the server from the current task projection. It is + a snapshot, not a reservation; claim a task lease before starting work. + Pass `explain=true` to include every open task with a stable readiness reason. + + Args: + 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_type` and `source_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 + """ + query: dict[str, object] = {} + if team is not None: + query["team"] = team + if org is not None: + query["org"] = org + if explain is not None: + query["explain"] = explain + if assigned_to_me is not None: + query["assigned_to_me"] = assigned_to_me + if source_scope is not None: + query["source_scope"] = source_scope + if source_type is not None: + query["source_type"] = source_type + if source_id is not None: + query["source_id"] = source_id + if epic is not None: + query["epic"] = epic + if limit is not None: + query["limit"] = limit + if after_cursor is not None: + query["after_cursor"] = after_cursor + return self._http.request( + f"/api/v1/users/{user}/tasks/ready", + query=query, + response_type=UserTaskReadyResponse, + ) + def search( self, user: str, @@ -3041,6 +3685,10 @@ def search( 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: @@ -3067,6 +3715,10 @@ def search( 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 pass `none` to return only top-level tasks. + source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_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. @@ -3094,6 +3746,14 @@ def search( query["tag"] = tag if parent is not None: query["parent"] = parent + if source_scope is not None: + query["source_scope"] = source_scope + if source_type is not None: + query["source_type"] = source_type + if source_id is not None: + query["source_id"] = source_id + if epic is not None: + query["epic"] = epic if limit is not None: query["limit"] = limit if after_cursor is not None: @@ -3174,11 +3834,91 @@ def create(self, user: str, input: UserThreadCreateInput) -> Thread: ) +class TokenResource: + def __init__(self, http: SyncHttpClient): + self._http = http + + def list(self, user: str) -> 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). + + Args: + user: User ID (`usr_...`) or `me` for the authenticated user. + + Returns: + Successful response + """ + return self._http.request(f"/api/v1/users/{user}/tokens", response_type=TokenListResponse) + + def create(self, user: str, input: TokenCreateInput) -> SystemAccessToken: + """ + 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. + + Args: + user: User ID (`usr_...`) or `me` for the authenticated user. + input: Request body. + input.expires_in_days: Lifetime in days. One of `7`, `30`, `60`, `90`, or `365`. Defaults to `30`. + 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 `token` field contains the raw JWT and is present only in this response it is not stored and cannot be retrieved later. + """ + return self._http.request( + f"/api/v1/users/{user}/tokens", + method="POST", + body=input, + response_type=SystemAccessToken, + ) + + def delete(self, user: str, token: str) -> SystemAccessToken: + """ + 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. + + Args: + user: User ID (`usr_...`) or `me` for the authenticated user. + token: Access token ID (`sat_...`). Must belong to the authenticated user. + + Returns: + The revoked access token. The `revoked_at` field is populated with the time of revocation. + """ + return self._http.request( + f"/api/v1/users/{user}/tokens/{token}", + method="DELETE", + response_type=SystemAccessToken, + ) + + class UserResource: def __init__(self, http: SyncHttpClient): self._http = http self.tasks = UserTaskResource(http) self.threads = UserThreadResource(http) + self.tokens = TokenResource(http) def me(self) -> User: """ diff --git a/tests/contract/v1/test_ai.py b/tests/contract/v1/test_ai.py index aca8c56..ead5ba9 100644 --- a/tests/contract/v1/test_ai.py +++ b/tests/contract/v1/test_ai.py @@ -1,6 +1,6 @@ # Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. # This file is auto-generated by @archastro/sdk-generator. Do not edit. -# Content hash: a2dc8aa73739 +# Content hash: 256a7e298b64 import pytest from pydantic import BaseModel @@ -64,6 +64,16 @@ def test_ai_chat_models_error_401(): ec.close() +def test_ai_chat_models_error_403(): + ec = _error_client(403) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.ai.chat.models() + assert exc_info.value.status == 403 + finally: + ec.close() + + @pytest.mark.asyncio async def test_async_ai_chat_models_success(): client = _async_client() @@ -87,6 +97,17 @@ async def test_async_ai_chat_models_error_401(): await ec.close() +@pytest.mark.asyncio +async def test_async_ai_chat_models_error_403(): + ec = _async_error_client(403) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.ai.chat.models() + assert exc_info.value.status == 403 + finally: + await ec.close() + + def test_ai_chat_completions_create_success(): client = _client() try: diff --git a/tests/contract/v1/test_event_subscription_deliveries.py b/tests/contract/v1/test_event_subscription_deliveries.py new file mode 100644 index 0000000..0f0eec9 --- /dev/null +++ b/tests/contract/v1/test_event_subscription_deliveries.py @@ -0,0 +1,140 @@ +# Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. +# This file is auto-generated by @archastro/sdk-generator. Do not edit. +# Content hash: d6aac84e4a62 + +import pytest + +from archastro.platform import AsyncPlatformClient, PlatformClient +from archastro.platform.runtime.http_client import ApiError + +PRISM_URL = "http://127.0.0.1:4040" + + +def _client() -> PlatformClient: + return PlatformClient( + base_url=PRISM_URL, + default_headers={"x-archastro-api-key": "pk_test-key"}, + access_token="test-token", + ) + + +def _error_client(code: int) -> PlatformClient: + return PlatformClient( + base_url=PRISM_URL, + default_headers={"x-archastro-api-key": "pk_test-key", "Prefer": f"code={code}"}, + access_token="test-token", + ) + + +def _async_client() -> AsyncPlatformClient: + return AsyncPlatformClient( + base_url=PRISM_URL, + default_headers={"x-archastro-api-key": "pk_test-key"}, + access_token="test-token", + ) + + +def _async_error_client(code: int) -> AsyncPlatformClient: + return AsyncPlatformClient( + base_url=PRISM_URL, + default_headers={"x-archastro-api-key": "pk_test-key", "Prefer": f"code={code}"}, + access_token="test-token", + ) + + +def test_event_subscription_deliveries_acknowledge_success(): + client = _client() + try: + result = client.v1.event_subscription_deliveries.acknowledge( + "test-value", {"receipt_handle": "test-value"} + ) + assert result is None + finally: + client.close() + + +def test_event_subscription_deliveries_acknowledge_error_401(): + ec = _error_client(401) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.event_subscription_deliveries.acknowledge( + "test-value", {"receipt_handle": "test-value"} + ) + assert exc_info.value.status == 401 + finally: + ec.close() + + +def test_event_subscription_deliveries_acknowledge_error_404(): + ec = _error_client(404) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.event_subscription_deliveries.acknowledge( + "test-value", {"receipt_handle": "test-value"} + ) + assert exc_info.value.status == 404 + finally: + ec.close() + + +def test_event_subscription_deliveries_acknowledge_error_409(): + ec = _error_client(409) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.event_subscription_deliveries.acknowledge( + "test-value", {"receipt_handle": "test-value"} + ) + assert exc_info.value.status == 409 + finally: + ec.close() + + +@pytest.mark.asyncio +async def test_async_event_subscription_deliveries_acknowledge_success(): + client = _async_client() + try: + result = await client.v1.event_subscription_deliveries.acknowledge( + "test-value", {"receipt_handle": "test-value"} + ) + assert result is None + finally: + await client.close() + + +@pytest.mark.asyncio +async def test_async_event_subscription_deliveries_acknowledge_error_401(): + ec = _async_error_client(401) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.event_subscription_deliveries.acknowledge( + "test-value", {"receipt_handle": "test-value"} + ) + assert exc_info.value.status == 401 + finally: + await ec.close() + + +@pytest.mark.asyncio +async def test_async_event_subscription_deliveries_acknowledge_error_404(): + ec = _async_error_client(404) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.event_subscription_deliveries.acknowledge( + "test-value", {"receipt_handle": "test-value"} + ) + assert exc_info.value.status == 404 + finally: + await ec.close() + + +@pytest.mark.asyncio +async def test_async_event_subscription_deliveries_acknowledge_error_409(): + ec = _async_error_client(409) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.event_subscription_deliveries.acknowledge( + "test-value", {"receipt_handle": "test-value"} + ) + assert exc_info.value.status == 409 + finally: + await ec.close() diff --git a/tests/contract/v1/test_event_subscriptions.py b/tests/contract/v1/test_event_subscriptions.py new file mode 100644 index 0000000..d0156cf --- /dev/null +++ b/tests/contract/v1/test_event_subscriptions.py @@ -0,0 +1,616 @@ +# Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. +# This file is auto-generated by @archastro/sdk-generator. Do not edit. +# Content hash: 7f15a27dc1ad + +import pytest +from pydantic import BaseModel + +from archastro.platform import AsyncPlatformClient, PlatformClient +from archastro.platform.runtime.http_client import ApiError + +PRISM_URL = "http://127.0.0.1:4040" + + +def _client() -> PlatformClient: + return PlatformClient( + base_url=PRISM_URL, + default_headers={"x-archastro-api-key": "pk_test-key"}, + access_token="test-token", + ) + + +def _error_client(code: int) -> PlatformClient: + return PlatformClient( + base_url=PRISM_URL, + default_headers={"x-archastro-api-key": "pk_test-key", "Prefer": f"code={code}"}, + access_token="test-token", + ) + + +def _async_client() -> AsyncPlatformClient: + return AsyncPlatformClient( + base_url=PRISM_URL, + default_headers={"x-archastro-api-key": "pk_test-key"}, + access_token="test-token", + ) + + +def _async_error_client(code: int) -> AsyncPlatformClient: + return AsyncPlatformClient( + base_url=PRISM_URL, + default_headers={"x-archastro-api-key": "pk_test-key", "Prefer": f"code={code}"}, + access_token="test-token", + ) + + +def test_event_subscriptions_list_success(): + client = _client() + try: + result = client.v1.event_subscriptions.list() + assert isinstance(result, BaseModel) + assert type(result).__name__ == "EventSubscriptionPage" + finally: + client.close() + + +def test_event_subscriptions_list_error_401(): + ec = _error_client(401) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.event_subscriptions.list() + assert exc_info.value.status == 401 + finally: + ec.close() + + +def test_event_subscriptions_list_error_422(): + ec = _error_client(422) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.event_subscriptions.list() + assert exc_info.value.status == 422 + finally: + ec.close() + + +@pytest.mark.asyncio +async def test_async_event_subscriptions_list_success(): + client = _async_client() + try: + result = await client.v1.event_subscriptions.list() + assert isinstance(result, BaseModel) + assert type(result).__name__ == "EventSubscriptionPage" + finally: + await client.close() + + +@pytest.mark.asyncio +async def test_async_event_subscriptions_list_error_401(): + ec = _async_error_client(401) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.event_subscriptions.list() + assert exc_info.value.status == 401 + finally: + await ec.close() + + +@pytest.mark.asyncio +async def test_async_event_subscriptions_list_error_422(): + ec = _async_error_client(422) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.event_subscriptions.list() + assert exc_info.value.status == 422 + finally: + await ec.close() + + +def test_event_subscriptions_create_success(): + client = _client() + try: + result = client.v1.event_subscriptions.create( + {"event_names": ["test-value"], "name": "test-name"} + ) + assert isinstance(result, BaseModel) + assert type(result).__name__ == "EventSubscription" + finally: + client.close() + + +def test_event_subscriptions_create_error_401(): + ec = _error_client(401) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.event_subscriptions.create({"event_names": ["test-value"], "name": "test-name"}) + assert exc_info.value.status == 401 + finally: + ec.close() + + +def test_event_subscriptions_create_error_422(): + ec = _error_client(422) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.event_subscriptions.create({"event_names": ["test-value"], "name": "test-name"}) + assert exc_info.value.status == 422 + finally: + ec.close() + + +@pytest.mark.asyncio +async def test_async_event_subscriptions_create_success(): + client = _async_client() + try: + result = await client.v1.event_subscriptions.create( + {"event_names": ["test-value"], "name": "test-name"} + ) + assert isinstance(result, BaseModel) + assert type(result).__name__ == "EventSubscription" + finally: + await client.close() + + +@pytest.mark.asyncio +async def test_async_event_subscriptions_create_error_401(): + ec = _async_error_client(401) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.event_subscriptions.create( + {"event_names": ["test-value"], "name": "test-name"} + ) + assert exc_info.value.status == 401 + finally: + await ec.close() + + +@pytest.mark.asyncio +async def test_async_event_subscriptions_create_error_422(): + ec = _async_error_client(422) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.event_subscriptions.create( + {"event_names": ["test-value"], "name": "test-name"} + ) + assert exc_info.value.status == 422 + finally: + await ec.close() + + +def test_event_subscriptions_delete_success(): + client = _client() + try: + result = client.v1.event_subscriptions.delete("test-value") + assert result is None + finally: + client.close() + + +def test_event_subscriptions_delete_error_401(): + ec = _error_client(401) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.event_subscriptions.delete("test-value") + assert exc_info.value.status == 401 + finally: + ec.close() + + +def test_event_subscriptions_delete_error_404(): + ec = _error_client(404) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.event_subscriptions.delete("test-value") + assert exc_info.value.status == 404 + finally: + ec.close() + + +@pytest.mark.asyncio +async def test_async_event_subscriptions_delete_success(): + client = _async_client() + try: + result = await client.v1.event_subscriptions.delete("test-value") + assert result is None + finally: + await client.close() + + +@pytest.mark.asyncio +async def test_async_event_subscriptions_delete_error_401(): + ec = _async_error_client(401) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.event_subscriptions.delete("test-value") + assert exc_info.value.status == 401 + finally: + await ec.close() + + +@pytest.mark.asyncio +async def test_async_event_subscriptions_delete_error_404(): + ec = _async_error_client(404) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.event_subscriptions.delete("test-value") + assert exc_info.value.status == 404 + finally: + await ec.close() + + +def test_event_subscriptions_get_success(): + client = _client() + try: + result = client.v1.event_subscriptions.get("test-value") + assert isinstance(result, BaseModel) + assert type(result).__name__ == "EventSubscription" + finally: + client.close() + + +def test_event_subscriptions_get_error_401(): + ec = _error_client(401) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.event_subscriptions.get("test-value") + assert exc_info.value.status == 401 + finally: + ec.close() + + +def test_event_subscriptions_get_error_404(): + ec = _error_client(404) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.event_subscriptions.get("test-value") + assert exc_info.value.status == 404 + finally: + ec.close() + + +@pytest.mark.asyncio +async def test_async_event_subscriptions_get_success(): + client = _async_client() + try: + result = await client.v1.event_subscriptions.get("test-value") + assert isinstance(result, BaseModel) + assert type(result).__name__ == "EventSubscription" + finally: + await client.close() + + +@pytest.mark.asyncio +async def test_async_event_subscriptions_get_error_401(): + ec = _async_error_client(401) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.event_subscriptions.get("test-value") + assert exc_info.value.status == 401 + finally: + await ec.close() + + +@pytest.mark.asyncio +async def test_async_event_subscriptions_get_error_404(): + ec = _async_error_client(404) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.event_subscriptions.get("test-value") + assert exc_info.value.status == 404 + finally: + await ec.close() + + +def test_event_subscriptions_update_success(): + client = _client() + try: + result = client.v1.event_subscriptions.update("test-value", {}) + assert isinstance(result, BaseModel) + assert type(result).__name__ == "EventSubscription" + finally: + client.close() + + +def test_event_subscriptions_update_error_401(): + ec = _error_client(401) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.event_subscriptions.update("test-value", {}) + assert exc_info.value.status == 401 + finally: + ec.close() + + +def test_event_subscriptions_update_error_404(): + ec = _error_client(404) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.event_subscriptions.update("test-value", {}) + assert exc_info.value.status == 404 + finally: + ec.close() + + +def test_event_subscriptions_update_error_422(): + ec = _error_client(422) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.event_subscriptions.update("test-value", {}) + assert exc_info.value.status == 422 + finally: + ec.close() + + +@pytest.mark.asyncio +async def test_async_event_subscriptions_update_success(): + client = _async_client() + try: + result = await client.v1.event_subscriptions.update("test-value", {}) + assert isinstance(result, BaseModel) + assert type(result).__name__ == "EventSubscription" + finally: + await client.close() + + +@pytest.mark.asyncio +async def test_async_event_subscriptions_update_error_401(): + ec = _async_error_client(401) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.event_subscriptions.update("test-value", {}) + assert exc_info.value.status == 401 + finally: + await ec.close() + + +@pytest.mark.asyncio +async def test_async_event_subscriptions_update_error_404(): + ec = _async_error_client(404) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.event_subscriptions.update("test-value", {}) + assert exc_info.value.status == 404 + finally: + await ec.close() + + +@pytest.mark.asyncio +async def test_async_event_subscriptions_update_error_422(): + ec = _async_error_client(422) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.event_subscriptions.update("test-value", {}) + assert exc_info.value.status == 422 + finally: + await ec.close() + + +def test_event_subscriptions_claim_success(): + client = _client() + try: + result = client.v1.event_subscriptions.claim("test-value", {}) + assert isinstance(result, BaseModel) + assert type(result).__name__ == "EventSubscriptionClaim" + finally: + client.close() + + +def test_event_subscriptions_claim_error_401(): + ec = _error_client(401) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.event_subscriptions.claim("test-value", {}) + assert exc_info.value.status == 401 + finally: + ec.close() + + +def test_event_subscriptions_claim_error_404(): + ec = _error_client(404) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.event_subscriptions.claim("test-value", {}) + assert exc_info.value.status == 404 + finally: + ec.close() + + +def test_event_subscriptions_claim_error_422(): + ec = _error_client(422) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.event_subscriptions.claim("test-value", {}) + assert exc_info.value.status == 422 + finally: + ec.close() + + +@pytest.mark.asyncio +async def test_async_event_subscriptions_claim_success(): + client = _async_client() + try: + result = await client.v1.event_subscriptions.claim("test-value", {}) + assert isinstance(result, BaseModel) + assert type(result).__name__ == "EventSubscriptionClaim" + finally: + await client.close() + + +@pytest.mark.asyncio +async def test_async_event_subscriptions_claim_error_401(): + ec = _async_error_client(401) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.event_subscriptions.claim("test-value", {}) + assert exc_info.value.status == 401 + finally: + await ec.close() + + +@pytest.mark.asyncio +async def test_async_event_subscriptions_claim_error_404(): + ec = _async_error_client(404) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.event_subscriptions.claim("test-value", {}) + assert exc_info.value.status == 404 + finally: + await ec.close() + + +@pytest.mark.asyncio +async def test_async_event_subscriptions_claim_error_422(): + ec = _async_error_client(422) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.event_subscriptions.claim("test-value", {}) + assert exc_info.value.status == 422 + finally: + await ec.close() + + +def test_event_subscriptions_head_success(): + client = _client() + try: + result = client.v1.event_subscriptions.head("test-value") + assert isinstance(result, BaseModel) + assert type(result).__name__ == "EventSubscriptionHead" + finally: + client.close() + + +def test_event_subscriptions_head_error_401(): + ec = _error_client(401) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.event_subscriptions.head("test-value") + assert exc_info.value.status == 401 + finally: + ec.close() + + +def test_event_subscriptions_head_error_404(): + ec = _error_client(404) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.event_subscriptions.head("test-value") + assert exc_info.value.status == 404 + finally: + ec.close() + + +@pytest.mark.asyncio +async def test_async_event_subscriptions_head_success(): + client = _async_client() + try: + result = await client.v1.event_subscriptions.head("test-value") + assert isinstance(result, BaseModel) + assert type(result).__name__ == "EventSubscriptionHead" + finally: + await client.close() + + +@pytest.mark.asyncio +async def test_async_event_subscriptions_head_error_401(): + ec = _async_error_client(401) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.event_subscriptions.head("test-value") + assert exc_info.value.status == 401 + finally: + await ec.close() + + +@pytest.mark.asyncio +async def test_async_event_subscriptions_head_error_404(): + ec = _async_error_client(404) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.event_subscriptions.head("test-value") + assert exc_info.value.status == 404 + finally: + await ec.close() + + +def test_event_subscriptions_queue_success(): + client = _client() + try: + result = client.v1.event_subscriptions.queue("test-value") + assert isinstance(result, BaseModel) + assert type(result).__name__ == "EventSubscriptionQueue" + finally: + client.close() + + +def test_event_subscriptions_queue_error_400(): + ec = _error_client(400) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.event_subscriptions.queue("test-value") + assert exc_info.value.status == 400 + finally: + ec.close() + + +def test_event_subscriptions_queue_error_401(): + ec = _error_client(401) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.event_subscriptions.queue("test-value") + assert exc_info.value.status == 401 + finally: + ec.close() + + +def test_event_subscriptions_queue_error_404(): + ec = _error_client(404) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.event_subscriptions.queue("test-value") + assert exc_info.value.status == 404 + finally: + ec.close() + + +@pytest.mark.asyncio +async def test_async_event_subscriptions_queue_success(): + client = _async_client() + try: + result = await client.v1.event_subscriptions.queue("test-value") + assert isinstance(result, BaseModel) + assert type(result).__name__ == "EventSubscriptionQueue" + finally: + await client.close() + + +@pytest.mark.asyncio +async def test_async_event_subscriptions_queue_error_400(): + ec = _async_error_client(400) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.event_subscriptions.queue("test-value") + assert exc_info.value.status == 400 + finally: + await ec.close() + + +@pytest.mark.asyncio +async def test_async_event_subscriptions_queue_error_401(): + ec = _async_error_client(401) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.event_subscriptions.queue("test-value") + assert exc_info.value.status == 401 + finally: + await ec.close() + + +@pytest.mark.asyncio +async def test_async_event_subscriptions_queue_error_404(): + ec = _async_error_client(404) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.event_subscriptions.queue("test-value") + assert exc_info.value.status == 404 + finally: + await ec.close() diff --git a/tests/contract/v1/test_knowledge_sources.py b/tests/contract/v1/test_knowledge_sources.py index 07fc0ef..cb04841 100644 --- a/tests/contract/v1/test_knowledge_sources.py +++ b/tests/contract/v1/test_knowledge_sources.py @@ -1,6 +1,6 @@ # Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. # This file is auto-generated by @archastro/sdk-generator. Do not edit. -# Content hash: 70ac81c9c642 +# Content hash: 7abc9cc5fbcf import pytest from pydantic import BaseModel @@ -148,6 +148,16 @@ def test_knowledge_sources_create_error_422(): ec.close() +def test_knowledge_sources_create_error_502(): + ec = _error_client(502) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.knowledge_sources.create({"type": "test"}) + assert exc_info.value.status == 502 + finally: + ec.close() + + @pytest.mark.asyncio async def test_async_knowledge_sources_create_success(): client = _async_client() @@ -192,6 +202,17 @@ async def test_async_knowledge_sources_create_error_422(): await ec.close() +@pytest.mark.asyncio +async def test_async_knowledge_sources_create_error_502(): + ec = _async_error_client(502) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.knowledge_sources.create({"type": "test"}) + assert exc_info.value.status == 502 + finally: + await ec.close() + + def test_knowledge_sources_delete_success(): client = _client() try: @@ -408,6 +429,16 @@ def test_knowledge_sources_update_error_422(): ec.close() +def test_knowledge_sources_update_error_502(): + ec = _error_client(502) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.knowledge_sources.update("test-value", {}) + assert exc_info.value.status == 502 + finally: + ec.close() + + @pytest.mark.asyncio async def test_async_knowledge_sources_update_success(): client = _async_client() @@ -463,6 +494,17 @@ async def test_async_knowledge_sources_update_error_422(): await ec.close() +@pytest.mark.asyncio +async def test_async_knowledge_sources_update_error_502(): + ec = _async_error_client(502) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.knowledge_sources.update("test-value", {}) + assert exc_info.value.status == 502 + finally: + await ec.close() + + def test_knowledge_sources_ingest_success(): client = _client() try: diff --git a/tests/contract/v1/test_oauth.py b/tests/contract/v1/test_oauth.py index 4eae498..495cd15 100644 --- a/tests/contract/v1/test_oauth.py +++ b/tests/contract/v1/test_oauth.py @@ -1,6 +1,6 @@ # Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. # This file is auto-generated by @archastro/sdk-generator. Do not edit. -# Content hash: dccf8b33bac0 +# Content hash: 302401dfe8b9 import pytest from pydantic import BaseModel @@ -211,6 +211,69 @@ async def test_async_oauth_device_approve_error_401(): await ec.close() +def test_oauth_device_authorization_success(): + client = _client() + try: + result = client.v1.oauth.device.authorization(code="test-value") + assert isinstance(result, BaseModel) + assert type(result).__name__ == "DeviceAuthorizationDetailsResponse" + finally: + client.close() + + +def test_oauth_device_authorization_error_400(): + ec = _error_client(400) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.oauth.device.authorization(code="test-value") + assert exc_info.value.status == 400 + finally: + ec.close() + + +def test_oauth_device_authorization_error_401(): + ec = _error_client(401) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.oauth.device.authorization(code="test-value") + assert exc_info.value.status == 401 + finally: + ec.close() + + +@pytest.mark.asyncio +async def test_async_oauth_device_authorization_success(): + client = _async_client() + try: + result = await client.v1.oauth.device.authorization(code="test-value") + assert isinstance(result, BaseModel) + assert type(result).__name__ == "DeviceAuthorizationDetailsResponse" + finally: + await client.close() + + +@pytest.mark.asyncio +async def test_async_oauth_device_authorization_error_400(): + ec = _async_error_client(400) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.oauth.device.authorization(code="test-value") + assert exc_info.value.status == 400 + finally: + await ec.close() + + +@pytest.mark.asyncio +async def test_async_oauth_device_authorization_error_401(): + ec = _async_error_client(401) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.oauth.device.authorization(code="test-value") + assert exc_info.value.status == 401 + finally: + await ec.close() + + def test_oauth_device_authorize_success(): client = _client() try: diff --git a/tests/contract/v1/test_slack_channel_bindings.py b/tests/contract/v1/test_slack_channel_bindings.py index a1767a6..8d21fd6 100644 --- a/tests/contract/v1/test_slack_channel_bindings.py +++ b/tests/contract/v1/test_slack_channel_bindings.py @@ -1,6 +1,6 @@ # Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. # This file is auto-generated by @archastro/sdk-generator. Do not edit. -# Content hash: e710914f22f2 +# Content hash: d385d1360ea4 import pytest from pydantic import BaseModel @@ -423,6 +423,23 @@ def test_slack_channel_bindings_provision_error_401(): ec.close() +def test_slack_channel_bindings_provision_error_402(): + ec = _error_client(402) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.slack_channel_bindings.provision( + { + "customer_key": "test-key", + "customer_label": "test-value", + "slack_team_id": "test-id", + "template_config_id": "test-id", + } + ) + assert exc_info.value.status == 402 + finally: + ec.close() + + def test_slack_channel_bindings_provision_error_403(): ec = _error_client(403) try: @@ -562,6 +579,24 @@ async def test_async_slack_channel_bindings_provision_error_401(): await ec.close() +@pytest.mark.asyncio +async def test_async_slack_channel_bindings_provision_error_402(): + ec = _async_error_client(402) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.slack_channel_bindings.provision( + { + "customer_key": "test-key", + "customer_label": "test-value", + "slack_team_id": "test-id", + "template_config_id": "test-id", + } + ) + assert exc_info.value.status == 402 + finally: + await ec.close() + + @pytest.mark.asyncio async def test_async_slack_channel_bindings_provision_error_403(): ec = _async_error_client(403) @@ -904,6 +939,111 @@ async def test_async_slack_channel_bindings_get_error_422(): await ec.close() +def test_slack_channel_bindings_delivery_outcomes_success(): + client = _client() + try: + result = client.v1.slack_channel_bindings.delivery_outcomes("test-value") + assert isinstance(result, BaseModel) + assert type(result).__name__ == "SlackDeliveryOutcomeListResponse" + finally: + client.close() + + +def test_slack_channel_bindings_delivery_outcomes_error_400(): + ec = _error_client(400) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.slack_channel_bindings.delivery_outcomes("test-value") + assert exc_info.value.status == 400 + finally: + ec.close() + + +def test_slack_channel_bindings_delivery_outcomes_error_401(): + ec = _error_client(401) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.slack_channel_bindings.delivery_outcomes("test-value") + assert exc_info.value.status == 401 + finally: + ec.close() + + +def test_slack_channel_bindings_delivery_outcomes_error_403(): + ec = _error_client(403) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.slack_channel_bindings.delivery_outcomes("test-value") + assert exc_info.value.status == 403 + finally: + ec.close() + + +def test_slack_channel_bindings_delivery_outcomes_error_422(): + ec = _error_client(422) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.slack_channel_bindings.delivery_outcomes("test-value") + assert exc_info.value.status == 422 + finally: + ec.close() + + +@pytest.mark.asyncio +async def test_async_slack_channel_bindings_delivery_outcomes_success(): + client = _async_client() + try: + result = await client.v1.slack_channel_bindings.delivery_outcomes("test-value") + assert isinstance(result, BaseModel) + assert type(result).__name__ == "SlackDeliveryOutcomeListResponse" + finally: + await client.close() + + +@pytest.mark.asyncio +async def test_async_slack_channel_bindings_delivery_outcomes_error_400(): + ec = _async_error_client(400) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.slack_channel_bindings.delivery_outcomes("test-value") + assert exc_info.value.status == 400 + finally: + await ec.close() + + +@pytest.mark.asyncio +async def test_async_slack_channel_bindings_delivery_outcomes_error_401(): + ec = _async_error_client(401) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.slack_channel_bindings.delivery_outcomes("test-value") + assert exc_info.value.status == 401 + finally: + await ec.close() + + +@pytest.mark.asyncio +async def test_async_slack_channel_bindings_delivery_outcomes_error_403(): + ec = _async_error_client(403) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.slack_channel_bindings.delivery_outcomes("test-value") + assert exc_info.value.status == 403 + finally: + await ec.close() + + +@pytest.mark.asyncio +async def test_async_slack_channel_bindings_delivery_outcomes_error_422(): + ec = _async_error_client(422) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.slack_channel_bindings.delivery_outcomes("test-value") + assert exc_info.value.status == 422 + finally: + await ec.close() + + def test_slack_channel_bindings_deposit_thread_success(): client = _client() try: diff --git a/tests/contract/v1/test_solutions.py b/tests/contract/v1/test_solutions.py index 991448e..2016b4a 100644 --- a/tests/contract/v1/test_solutions.py +++ b/tests/contract/v1/test_solutions.py @@ -1,6 +1,6 @@ # Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. # This file is auto-generated by @archastro/sdk-generator. Do not edit. -# Content hash: b1d6f6ca9577 +# Content hash: 3661308a7997 import pytest from pydantic import BaseModel @@ -734,6 +734,132 @@ async def test_async_solutions_readme_error_404(): await ec.close() +def test_solutions_reconcile_product_knowledge_success(): + client = _client() + try: + result = client.v1.solutions.reconcile_product_knowledge("test-value") + assert isinstance(result, BaseModel) + assert type(result).__name__ == "ProductKnowledgeReconcileResponse" + finally: + client.close() + + +def test_solutions_reconcile_product_knowledge_error_400(): + ec = _error_client(400) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.solutions.reconcile_product_knowledge("test-value") + assert exc_info.value.status == 400 + finally: + ec.close() + + +def test_solutions_reconcile_product_knowledge_error_401(): + ec = _error_client(401) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.solutions.reconcile_product_knowledge("test-value") + assert exc_info.value.status == 401 + finally: + ec.close() + + +def test_solutions_reconcile_product_knowledge_error_403(): + ec = _error_client(403) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.solutions.reconcile_product_knowledge("test-value") + assert exc_info.value.status == 403 + finally: + ec.close() + + +def test_solutions_reconcile_product_knowledge_error_404(): + ec = _error_client(404) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.solutions.reconcile_product_knowledge("test-value") + assert exc_info.value.status == 404 + finally: + ec.close() + + +def test_solutions_reconcile_product_knowledge_error_502(): + ec = _error_client(502) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.solutions.reconcile_product_knowledge("test-value") + assert exc_info.value.status == 502 + finally: + ec.close() + + +@pytest.mark.asyncio +async def test_async_solutions_reconcile_product_knowledge_success(): + client = _async_client() + try: + result = await client.v1.solutions.reconcile_product_knowledge("test-value") + assert isinstance(result, BaseModel) + assert type(result).__name__ == "ProductKnowledgeReconcileResponse" + finally: + await client.close() + + +@pytest.mark.asyncio +async def test_async_solutions_reconcile_product_knowledge_error_400(): + ec = _async_error_client(400) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.solutions.reconcile_product_knowledge("test-value") + assert exc_info.value.status == 400 + finally: + await ec.close() + + +@pytest.mark.asyncio +async def test_async_solutions_reconcile_product_knowledge_error_401(): + ec = _async_error_client(401) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.solutions.reconcile_product_knowledge("test-value") + assert exc_info.value.status == 401 + finally: + await ec.close() + + +@pytest.mark.asyncio +async def test_async_solutions_reconcile_product_knowledge_error_403(): + ec = _async_error_client(403) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.solutions.reconcile_product_knowledge("test-value") + assert exc_info.value.status == 403 + finally: + await ec.close() + + +@pytest.mark.asyncio +async def test_async_solutions_reconcile_product_knowledge_error_404(): + ec = _async_error_client(404) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.solutions.reconcile_product_knowledge("test-value") + assert exc_info.value.status == 404 + finally: + await ec.close() + + +@pytest.mark.asyncio +async def test_async_solutions_reconcile_product_knowledge_error_502(): + ec = _async_error_client(502) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.solutions.reconcile_product_knowledge("test-value") + assert exc_info.value.status == 502 + finally: + await ec.close() + + def test_solutions_upgrade_success(): client = _client() try: diff --git a/tests/contract/v1/test_tasks.py b/tests/contract/v1/test_tasks.py index 5e23041..45c81f2 100644 --- a/tests/contract/v1/test_tasks.py +++ b/tests/contract/v1/test_tasks.py @@ -1,6 +1,6 @@ # Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. # This file is auto-generated by @archastro/sdk-generator. Do not edit. -# Content hash: 5e34468188ae +# Content hash: 9e68c7eadcfc import pytest from pydantic import BaseModel @@ -1818,3 +1818,250 @@ async def test_async_tasks_lease_renew_error_422(): assert exc_info.value.status == 422 finally: await ec.close() + + +def test_tasks_links_remove_success(): + client = _client() + try: + result = client.v1.tasks.links.remove("test-value") + assert result is None + finally: + client.close() + + +def test_tasks_links_remove_error_401(): + ec = _error_client(401) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.tasks.links.remove("test-value") + assert exc_info.value.status == 401 + finally: + ec.close() + + +def test_tasks_links_remove_error_404(): + ec = _error_client(404) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.tasks.links.remove("test-value") + assert exc_info.value.status == 404 + finally: + ec.close() + + +def test_tasks_links_remove_error_502(): + ec = _error_client(502) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.tasks.links.remove("test-value") + assert exc_info.value.status == 502 + finally: + ec.close() + + +@pytest.mark.asyncio +async def test_async_tasks_links_remove_success(): + client = _async_client() + try: + result = await client.v1.tasks.links.remove("test-value") + assert result is None + finally: + await client.close() + + +@pytest.mark.asyncio +async def test_async_tasks_links_remove_error_401(): + ec = _async_error_client(401) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.tasks.links.remove("test-value") + assert exc_info.value.status == 401 + finally: + await ec.close() + + +@pytest.mark.asyncio +async def test_async_tasks_links_remove_error_404(): + ec = _async_error_client(404) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.tasks.links.remove("test-value") + assert exc_info.value.status == 404 + finally: + await ec.close() + + +@pytest.mark.asyncio +async def test_async_tasks_links_remove_error_502(): + ec = _async_error_client(502) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.tasks.links.remove("test-value") + assert exc_info.value.status == 502 + finally: + await ec.close() + + +def test_tasks_links_create_success(): + client = _client() + try: + result = client.v1.tasks.links.create( + "test-value", + {"external_scope": "test-value", "object_id": "test-id", "object_type": "test-value"}, + ) + assert result is not None + finally: + client.close() + + +def test_tasks_links_create_error_401(): + ec = _error_client(401) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.tasks.links.create( + "test-value", + { + "external_scope": "test-value", + "object_id": "test-id", + "object_type": "test-value", + }, + ) + assert exc_info.value.status == 401 + finally: + ec.close() + + +def test_tasks_links_create_error_404(): + ec = _error_client(404) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.tasks.links.create( + "test-value", + { + "external_scope": "test-value", + "object_id": "test-id", + "object_type": "test-value", + }, + ) + assert exc_info.value.status == 404 + finally: + ec.close() + + +def test_tasks_links_create_error_422(): + ec = _error_client(422) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.tasks.links.create( + "test-value", + { + "external_scope": "test-value", + "object_id": "test-id", + "object_type": "test-value", + }, + ) + assert exc_info.value.status == 422 + finally: + ec.close() + + +def test_tasks_links_create_error_502(): + ec = _error_client(502) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.tasks.links.create( + "test-value", + { + "external_scope": "test-value", + "object_id": "test-id", + "object_type": "test-value", + }, + ) + assert exc_info.value.status == 502 + finally: + ec.close() + + +@pytest.mark.asyncio +async def test_async_tasks_links_create_success(): + client = _async_client() + try: + result = await client.v1.tasks.links.create( + "test-value", + {"external_scope": "test-value", "object_id": "test-id", "object_type": "test-value"}, + ) + assert result is not None + finally: + await client.close() + + +@pytest.mark.asyncio +async def test_async_tasks_links_create_error_401(): + ec = _async_error_client(401) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.tasks.links.create( + "test-value", + { + "external_scope": "test-value", + "object_id": "test-id", + "object_type": "test-value", + }, + ) + assert exc_info.value.status == 401 + finally: + await ec.close() + + +@pytest.mark.asyncio +async def test_async_tasks_links_create_error_404(): + ec = _async_error_client(404) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.tasks.links.create( + "test-value", + { + "external_scope": "test-value", + "object_id": "test-id", + "object_type": "test-value", + }, + ) + assert exc_info.value.status == 404 + finally: + await ec.close() + + +@pytest.mark.asyncio +async def test_async_tasks_links_create_error_422(): + ec = _async_error_client(422) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.tasks.links.create( + "test-value", + { + "external_scope": "test-value", + "object_id": "test-id", + "object_type": "test-value", + }, + ) + assert exc_info.value.status == 422 + finally: + await ec.close() + + +@pytest.mark.asyncio +async def test_async_tasks_links_create_error_502(): + ec = _async_error_client(502) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.tasks.links.create( + "test-value", + { + "external_scope": "test-value", + "object_id": "test-id", + "object_type": "test-value", + }, + ) + assert exc_info.value.status == 502 + finally: + await ec.close() diff --git a/tests/contract/v1/test_team_memberships.py b/tests/contract/v1/test_team_memberships.py index 2bc23cc..9b1dd46 100644 --- a/tests/contract/v1/test_team_memberships.py +++ b/tests/contract/v1/test_team_memberships.py @@ -1,6 +1,6 @@ # Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. # This file is auto-generated by @archastro/sdk-generator. Do not edit. -# Content hash: c6d59b858697 +# Content hash: 757b23a687d4 import pytest from pydantic import BaseModel @@ -125,6 +125,16 @@ def test_team_memberships_delete_error_401(): ec.close() +def test_team_memberships_delete_error_403(): + ec = _error_client(403) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.team_memberships.delete("test-value") + assert exc_info.value.status == 403 + finally: + ec.close() + + def test_team_memberships_delete_error_404(): ec = _error_client(404) try: @@ -156,6 +166,17 @@ async def test_async_team_memberships_delete_error_401(): await ec.close() +@pytest.mark.asyncio +async def test_async_team_memberships_delete_error_403(): + ec = _async_error_client(403) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.team_memberships.delete("test-value") + assert exc_info.value.status == 403 + finally: + await ec.close() + + @pytest.mark.asyncio async def test_async_team_memberships_delete_error_404(): ec = _async_error_client(404) diff --git a/tests/contract/v1/test_teams.py b/tests/contract/v1/test_teams.py index d0d7402..7b8820d 100644 --- a/tests/contract/v1/test_teams.py +++ b/tests/contract/v1/test_teams.py @@ -1,6 +1,6 @@ # Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. # This file is auto-generated by @archastro/sdk-generator. Do not edit. -# Content hash: dbdd5cbd2ce5 +# Content hash: 2b5338fb5372 import pytest from pydantic import BaseModel @@ -1962,6 +1962,92 @@ async def test_async_teams_tasks_metrics_error_422(): await ec.close() +def test_teams_tasks_ready_success(): + client = _client() + try: + result = client.v1.teams.tasks.ready("test-value") + assert isinstance(result, BaseModel) + assert type(result).__name__ == "TeamTaskReadyResponse" + assert isinstance(result.data, list) + finally: + client.close() + + +def test_teams_tasks_ready_error_401(): + ec = _error_client(401) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.teams.tasks.ready("test-value") + assert exc_info.value.status == 401 + finally: + ec.close() + + +def test_teams_tasks_ready_error_404(): + ec = _error_client(404) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.teams.tasks.ready("test-value") + assert exc_info.value.status == 404 + finally: + ec.close() + + +def test_teams_tasks_ready_error_422(): + ec = _error_client(422) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.teams.tasks.ready("test-value") + assert exc_info.value.status == 422 + finally: + ec.close() + + +@pytest.mark.asyncio +async def test_async_teams_tasks_ready_success(): + client = _async_client() + try: + result = await client.v1.teams.tasks.ready("test-value") + assert isinstance(result, BaseModel) + assert type(result).__name__ == "TeamTaskReadyResponse" + assert isinstance(result.data, list) + finally: + await client.close() + + +@pytest.mark.asyncio +async def test_async_teams_tasks_ready_error_401(): + ec = _async_error_client(401) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.teams.tasks.ready("test-value") + assert exc_info.value.status == 401 + finally: + await ec.close() + + +@pytest.mark.asyncio +async def test_async_teams_tasks_ready_error_404(): + ec = _async_error_client(404) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.teams.tasks.ready("test-value") + assert exc_info.value.status == 404 + finally: + await ec.close() + + +@pytest.mark.asyncio +async def test_async_teams_tasks_ready_error_422(): + ec = _async_error_client(422) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.teams.tasks.ready("test-value") + assert exc_info.value.status == 422 + finally: + await ec.close() + + def test_teams_tasks_search_success(): client = _client() try: diff --git a/tests/contract/v1/test_threads.py b/tests/contract/v1/test_threads.py index 6493688..0723fd6 100644 --- a/tests/contract/v1/test_threads.py +++ b/tests/contract/v1/test_threads.py @@ -1,6 +1,6 @@ # Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. # This file is auto-generated by @archastro/sdk-generator. Do not edit. -# Content hash: 5a5100e08192 +# Content hash: 42fb0c5c2ab6 import pytest from pydantic import BaseModel @@ -1133,6 +1133,16 @@ def test_threads_trajectories_success(): client.close() +def test_threads_trajectories_error_400(): + ec = _error_client(400) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.threads.trajectories("test-value") + assert exc_info.value.status == 400 + finally: + ec.close() + + def test_threads_trajectories_error_401(): ec = _error_client(401) try: @@ -1175,6 +1185,17 @@ async def test_async_threads_trajectories_success(): await client.close() +@pytest.mark.asyncio +async def test_async_threads_trajectories_error_400(): + ec = _async_error_client(400) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.threads.trajectories("test-value") + assert exc_info.value.status == 400 + finally: + await ec.close() + + @pytest.mark.asyncio async def test_async_threads_trajectories_error_401(): ec = _async_error_client(401) diff --git a/tests/contract/v1/test_users.py b/tests/contract/v1/test_users.py index 6424081..5a6a58c 100644 --- a/tests/contract/v1/test_users.py +++ b/tests/contract/v1/test_users.py @@ -1,6 +1,6 @@ # Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. # This file is auto-generated by @archastro/sdk-generator. Do not edit. -# Content hash: 6406711dfbf0 +# Content hash: 68e4b3af77bf import pytest from pydantic import BaseModel @@ -702,6 +702,92 @@ async def test_async_users_tasks_blocker_cycles_error_422(): await ec.close() +def test_users_tasks_ready_success(): + client = _client() + try: + result = client.v1.users.tasks.ready("test-value") + assert isinstance(result, BaseModel) + assert type(result).__name__ == "UserTaskReadyResponse" + assert isinstance(result.data, list) + finally: + client.close() + + +def test_users_tasks_ready_error_401(): + ec = _error_client(401) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.users.tasks.ready("test-value") + assert exc_info.value.status == 401 + finally: + ec.close() + + +def test_users_tasks_ready_error_404(): + ec = _error_client(404) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.users.tasks.ready("test-value") + assert exc_info.value.status == 404 + finally: + ec.close() + + +def test_users_tasks_ready_error_422(): + ec = _error_client(422) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.users.tasks.ready("test-value") + assert exc_info.value.status == 422 + finally: + ec.close() + + +@pytest.mark.asyncio +async def test_async_users_tasks_ready_success(): + client = _async_client() + try: + result = await client.v1.users.tasks.ready("test-value") + assert isinstance(result, BaseModel) + assert type(result).__name__ == "UserTaskReadyResponse" + assert isinstance(result.data, list) + finally: + await client.close() + + +@pytest.mark.asyncio +async def test_async_users_tasks_ready_error_401(): + ec = _async_error_client(401) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.users.tasks.ready("test-value") + assert exc_info.value.status == 401 + finally: + await ec.close() + + +@pytest.mark.asyncio +async def test_async_users_tasks_ready_error_404(): + ec = _async_error_client(404) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.users.tasks.ready("test-value") + assert exc_info.value.status == 404 + finally: + await ec.close() + + +@pytest.mark.asyncio +async def test_async_users_tasks_ready_error_422(): + ec = _async_error_client(422) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.users.tasks.ready("test-value") + assert exc_info.value.status == 422 + finally: + await ec.close() + + def test_users_tasks_search_success(): client = _client() try: @@ -935,3 +1021,257 @@ async def test_async_users_threads_create_error_422(): assert exc_info.value.status == 422 finally: await ec.close() + + +def test_users_tokens_list_success(): + client = _client() + try: + result = client.v1.users.tokens.list("test-value") + assert isinstance(result, BaseModel) + assert type(result).__name__ == "TokenListResponse" + assert isinstance(result.data, list) + finally: + client.close() + + +def test_users_tokens_list_error_401(): + ec = _error_client(401) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.users.tokens.list("test-value") + assert exc_info.value.status == 401 + finally: + ec.close() + + +def test_users_tokens_list_error_403(): + ec = _error_client(403) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.users.tokens.list("test-value") + assert exc_info.value.status == 403 + finally: + ec.close() + + +@pytest.mark.asyncio +async def test_async_users_tokens_list_success(): + client = _async_client() + try: + result = await client.v1.users.tokens.list("test-value") + assert isinstance(result, BaseModel) + assert type(result).__name__ == "TokenListResponse" + assert isinstance(result.data, list) + finally: + await client.close() + + +@pytest.mark.asyncio +async def test_async_users_tokens_list_error_401(): + ec = _async_error_client(401) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.users.tokens.list("test-value") + assert exc_info.value.status == 401 + finally: + await ec.close() + + +@pytest.mark.asyncio +async def test_async_users_tokens_list_error_403(): + ec = _async_error_client(403) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.users.tokens.list("test-value") + assert exc_info.value.status == 403 + finally: + await ec.close() + + +def test_users_tokens_create_success(): + client = _client() + try: + result = client.v1.users.tokens.create("test-value", {}) + assert isinstance(result, BaseModel) + assert type(result).__name__ == "SystemAccessToken" + finally: + client.close() + + +def test_users_tokens_create_error_401(): + ec = _error_client(401) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.users.tokens.create("test-value", {}) + assert exc_info.value.status == 401 + finally: + ec.close() + + +def test_users_tokens_create_error_403(): + ec = _error_client(403) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.users.tokens.create("test-value", {}) + assert exc_info.value.status == 403 + finally: + ec.close() + + +def test_users_tokens_create_error_422(): + ec = _error_client(422) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.users.tokens.create("test-value", {}) + assert exc_info.value.status == 422 + finally: + ec.close() + + +def test_users_tokens_create_error_429(): + ec = _error_client(429) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.users.tokens.create("test-value", {}) + assert exc_info.value.status == 429 + finally: + ec.close() + + +@pytest.mark.asyncio +async def test_async_users_tokens_create_success(): + client = _async_client() + try: + result = await client.v1.users.tokens.create("test-value", {}) + assert isinstance(result, BaseModel) + assert type(result).__name__ == "SystemAccessToken" + finally: + await client.close() + + +@pytest.mark.asyncio +async def test_async_users_tokens_create_error_401(): + ec = _async_error_client(401) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.users.tokens.create("test-value", {}) + assert exc_info.value.status == 401 + finally: + await ec.close() + + +@pytest.mark.asyncio +async def test_async_users_tokens_create_error_403(): + ec = _async_error_client(403) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.users.tokens.create("test-value", {}) + assert exc_info.value.status == 403 + finally: + await ec.close() + + +@pytest.mark.asyncio +async def test_async_users_tokens_create_error_422(): + ec = _async_error_client(422) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.users.tokens.create("test-value", {}) + assert exc_info.value.status == 422 + finally: + await ec.close() + + +@pytest.mark.asyncio +async def test_async_users_tokens_create_error_429(): + ec = _async_error_client(429) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.users.tokens.create("test-value", {}) + assert exc_info.value.status == 429 + finally: + await ec.close() + + +def test_users_tokens_delete_success(): + client = _client() + try: + result = client.v1.users.tokens.delete("test-value", "test-token") + assert isinstance(result, BaseModel) + assert type(result).__name__ == "SystemAccessToken" + finally: + client.close() + + +def test_users_tokens_delete_error_401(): + ec = _error_client(401) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.users.tokens.delete("test-value", "test-token") + assert exc_info.value.status == 401 + finally: + ec.close() + + +def test_users_tokens_delete_error_403(): + ec = _error_client(403) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.users.tokens.delete("test-value", "test-token") + assert exc_info.value.status == 403 + finally: + ec.close() + + +def test_users_tokens_delete_error_404(): + ec = _error_client(404) + try: + with pytest.raises(ApiError) as exc_info: + ec.v1.users.tokens.delete("test-value", "test-token") + assert exc_info.value.status == 404 + finally: + ec.close() + + +@pytest.mark.asyncio +async def test_async_users_tokens_delete_success(): + client = _async_client() + try: + result = await client.v1.users.tokens.delete("test-value", "test-token") + assert isinstance(result, BaseModel) + assert type(result).__name__ == "SystemAccessToken" + finally: + await client.close() + + +@pytest.mark.asyncio +async def test_async_users_tokens_delete_error_401(): + ec = _async_error_client(401) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.users.tokens.delete("test-value", "test-token") + assert exc_info.value.status == 401 + finally: + await ec.close() + + +@pytest.mark.asyncio +async def test_async_users_tokens_delete_error_403(): + ec = _async_error_client(403) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.users.tokens.delete("test-value", "test-token") + assert exc_info.value.status == 403 + finally: + await ec.close() + + +@pytest.mark.asyncio +async def test_async_users_tokens_delete_error_404(): + ec = _async_error_client(404) + try: + with pytest.raises(ApiError) as exc_info: + await ec.v1.users.tokens.delete("test-value", "test-token") + assert exc_info.value.status == 404 + finally: + await ec.close() From 261184b5c3cc31326f2be30c093b9aa8d6dff6ac Mon Sep 17 00:00:00 2001 From: Rafael Brandao Date: Tue, 18 Aug 2026 08:27:30 -0700 Subject: [PATCH 2/2] sdk: align with archastro-openapi main spec MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The event-subscriptions surface this PR adds is byte-identical when regenerated against main — the spec landed there via the automated refresh after firstlanding #10337 merged (the companion spec PR #82 was closed as redundant). This commit picks up the unrelated chat/threads/teams/users drift between the branch-vintage spec and main's snapshot so the PR regenerates cleanly from main. Full suite green (2676 tests). --- specs/platform-openapi.json | 381 +++++++----------- .../platform/channels/api_chat_channel.py | 12 +- src/archastro/platform/types/chat.py | 22 +- src/archastro/platform/types/threads.py | 4 +- src/archastro/platform/v1/resources/teams.py | 18 +- src/archastro/platform/v1/resources/users.py | 16 +- .../channels/test_api_chat_channel.py | 24 +- 7 files changed, 209 insertions(+), 268 deletions(-) diff --git a/specs/platform-openapi.json b/specs/platform-openapi.json index 71b5c7e..4f8d6be 100644 --- a/specs/platform-openapi.json +++ b/specs/platform-openapi.json @@ -1613,7 +1613,6 @@ "required": true, "type": "agent_user" }, - "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", @@ -2140,7 +2139,6 @@ "required": true, "type": "agent_user" }, - "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", @@ -9516,6 +9514,62 @@ ], "type": "object" }, + "ChatLocalToolDefinition": { + "description": "An OpenAI-compatible local function definition supplied while joining a personal thread.", + "example": { + "function": { + "description": "An example description.", + "name": "Example Name", + "parameters": {} + }, + "type": "function" + }, + "properties": { + "function": { + "$ref": "#/components/schemas/ChatLocalToolFunction" + }, + "type": { + "enum": [ + "function" + ], + "example": "function", + "type": "string" + } + }, + "required": [ + "type", + "function" + ], + "type": "object" + }, + "ChatLocalToolFunction": { + "description": "A function implemented by the client connected to a personal thread.", + "example": { + "description": "An example description.", + "name": "Example Name", + "parameters": {} + }, + "properties": { + "description": { + "example": "An example description.", + "type": "string" + }, + "name": { + "example": "Example Name", + "type": "string" + }, + "parameters": { + "example": {}, + "type": "object" + } + }, + "required": [ + "name", + "description", + "parameters" + ], + "type": "object" + }, "ChatMarkThreadReadResponse": { "description": "Response returned after marking a chat thread as read. Confirms that the read marker was successfully recorded for the authenticated user.", "example": { @@ -16299,21 +16353,8 @@ }, "participants": { "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.", - "example": [ - { - "description": "An example description.", - "name": "reporter", - "required": true, - "type": "agent_user" - } - ], "items": { - "allOf": [ - { - "$ref": "#/components/schemas/AutomationParticipantSlot" - } - ], - "nullable": true + "$ref": "#/components/schemas/AutomationParticipantSlot" }, "nullable": true, "type": "array" @@ -20841,196 +20882,8 @@ }, "participating_agents": { "description": "Expanded agent objects for all agents participating in this thread. Present only when agent enrichment is requested.", - "example": [ - { - "acl": { - "add": [ - { - "actions": [ - "read", - "write" - ], - "principal": "string", - "principal_type": "user" - } - ], - "grants": [ - { - "actions": [ - "read", - "write" - ], - "principal": "string", - "principal_type": "user" - } - ], - "remove": [ - { - "principal": "string", - "principal_type": "user" - } - ] - }, - "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", - "created_at": "2024-01-01T00:00:00Z", - "default_model": "claude-3-7-sonnet-latest", - "description": "An example description.", - "email": "user@example.com", - "id": "agi_0aBcDeFgHiJkLmNoPqRsTu", - "identity": "You are a helpful assistant that answers questions about ArchAstro products.", - "last_applied_template_config": "cfg_0aBcDeFgHiJkLmNoPqRsTu", - "lookup_key": "string", - "metadata": { - "key": "value" - }, - "name": "Example Name", - "org": "org_0aBcDeFgHiJkLmNoPqRsTu", - "org_name": "Example Name", - "originator": "deploy-pipeline", - "phone_number": "+15555550123", - "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", - "source_solution": { - "current_solution": { - "category_keys": [ - "string" - ], - "created_at": "2024-01-01T00:00:00Z", - "description": "An example description.", - "events": {}, - "id": "id_0aBcDeFgHiJkLmNoPqRsTu", - "image_url": "https://example.com", - "kind": "Solution", - "latest_solution": "id_0aBcDeFgHiJkLmNoPqRsTu", - "latest_version": "1.0.0", - "lookup_key": "string", - "metadata": { - "key": "value" - }, - "name": "Example Name", - "org": "org_0aBcDeFgHiJkLmNoPqRsTu", - "org_logo": { - "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", - "height": 600, - "media": "med_0aBcDeFgHiJkLmNoPqRsTu", - "mime_type": "application/json", - "refresh_url": "https://example.com", - "url": "https://example.com", - "width": 800 - }, - "org_name": "Example Name", - "org_slug": "example-slug", - "owners": [ - "string" - ], - "readme_url": "https://example.com", - "screenshot_urls": [ - "https://example.com" - ], - "solution_id": "01234567-89ab-cdef-0123-456789abcdef", - "solution_version": "1.2.0", - "tag_keys": [ - "string" - ], - "template_kind": "AgentTemplate", - "templates": [ - { - "description": "An example description.", - "display_name": "Example Name", - "id": "id_0aBcDeFgHiJkLmNoPqRsTu", - "kind": "AgentTemplate", - "lookup_key": "string", - "name": "Example Name", - "readme_url": "https://example.com", - "virtual_path": "string" - } - ], - "updated_at": "2024-01-01T00:00:00Z", - "upgrade_available": true, - "virtual_path": "string" - }, - "solution": { - "category_keys": [ - "string" - ], - "created_at": "2024-01-01T00:00:00Z", - "description": "An example description.", - "events": {}, - "id": "id_0aBcDeFgHiJkLmNoPqRsTu", - "image_url": "https://example.com", - "kind": "Solution", - "latest_solution": "id_0aBcDeFgHiJkLmNoPqRsTu", - "latest_version": "1.0.0", - "lookup_key": "string", - "metadata": { - "key": "value" - }, - "name": "Example Name", - "org": "org_0aBcDeFgHiJkLmNoPqRsTu", - "org_logo": { - "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", - "height": 600, - "media": "med_0aBcDeFgHiJkLmNoPqRsTu", - "mime_type": "application/json", - "refresh_url": "https://example.com", - "url": "https://example.com", - "width": 800 - }, - "org_name": "Example Name", - "org_slug": "example-slug", - "owners": [ - "string" - ], - "readme_url": "https://example.com", - "screenshot_urls": [ - "https://example.com" - ], - "solution_id": "01234567-89ab-cdef-0123-456789abcdef", - "solution_version": "1.2.0", - "tag_keys": [ - "string" - ], - "template_kind": "AgentTemplate", - "templates": [ - { - "description": "An example description.", - "display_name": "Example Name", - "id": "id_0aBcDeFgHiJkLmNoPqRsTu", - "kind": "AgentTemplate", - "lookup_key": "string", - "name": "Example Name", - "readme_url": "https://example.com", - "virtual_path": "string" - } - ], - "updated_at": "2024-01-01T00:00:00Z", - "upgrade_available": true, - "virtual_path": "string" - }, - "template": { - "created_at": "2024-01-01T00:00:00Z", - "description": "An example description.", - "display_name": "Example Name", - "id": "id_0aBcDeFgHiJkLmNoPqRsTu", - "kind": "agent_tool_template", - "lookup_key": "string", - "name": "Example Name", - "updated_at": "2024-01-01T00:00:00Z", - "virtual_path": "string" - } - }, - "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", - "template_upgrade_available": true, - "updated_at": "2024-01-01T00:00:00Z", - "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" - } - ], "items": { - "allOf": [ - { - "$ref": "#/components/schemas/Agent" - } - ], - "nullable": true + "$ref": "#/components/schemas/Agent" }, "nullable": true, "type": "array" @@ -21063,7 +20916,6 @@ {} ], "items": { - "nullable": true, "type": "object" }, "nullable": true, @@ -23509,7 +23361,6 @@ "required": true, "type": "agent_user" }, - "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", @@ -24036,7 +23887,6 @@ "required": true, "type": "agent_user" }, - "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", @@ -54518,7 +54368,6 @@ "required": true, "type": "agent_user" }, - "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", @@ -55045,7 +54894,6 @@ "required": true, "type": "agent_user" }, - "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", @@ -63400,7 +63248,6 @@ "updated_at": "string", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" }, - "nullable": true, "properties": { "acl": { "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.", @@ -64177,7 +64024,6 @@ "required": true, "type": "agent_user" }, - "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", @@ -64704,7 +64550,6 @@ "required": true, "type": "agent_user" }, - "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", @@ -65007,7 +64852,6 @@ {} ], "items": { - "nullable": true, "type": "object" }, "nullable": true, @@ -78436,7 +78280,6 @@ "updated_at": "string", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" }, - "nullable": true, "properties": { "acl": { "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.", @@ -79213,7 +79056,6 @@ "required": true, "type": "agent_user" }, - "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", @@ -79740,7 +79582,6 @@ "required": true, "type": "agent_user" }, - "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", @@ -80043,7 +79884,6 @@ {} ], "items": { - "nullable": true, "type": "object" }, "nullable": true, @@ -82601,7 +82441,6 @@ "required": true, "type": "agent_user" }, - "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", @@ -83128,7 +82967,6 @@ "required": true, "type": "agent_user" }, - "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", @@ -83840,7 +83678,7 @@ } }, { - "description": "Join a user-scoped thread by ID", + "description": "Join a user-scoped thread by ID, optionally supplying local tools for a personal thread", "name": "join_user_thread", "params": { "example": { @@ -83848,6 +83686,17 @@ "before_cursor": "string", "include_metadata": true, "limit": 1, + "local_tool_provider_id": "string", + "local_tools": [ + { + "function": { + "description": "An example description.", + "name": "Example Name", + "parameters": {} + }, + "type": "function" + } + ], "thread_id": "string" }, "properties": { @@ -83867,6 +83716,76 @@ "example": 1, "type": "integer" }, + "local_tool_provider_id": { + "example": "string", + "type": "string" + }, + "local_tools": { + "example": [ + { + "function": { + "description": "An example description.", + "name": "Example Name", + "parameters": {} + }, + "type": "function" + } + ], + "items": { + "description": "An OpenAI-compatible local function definition supplied while joining a personal thread.", + "example": { + "function": { + "description": "An example description.", + "name": "Example Name", + "parameters": {} + }, + "type": "function" + }, + "properties": { + "function": { + "description": "A function implemented by the client connected to a personal thread.", + "example": { + "description": "An example description.", + "name": "Example Name", + "parameters": {} + }, + "properties": { + "description": { + "example": "An example description.", + "type": "string" + }, + "name": { + "example": "Example Name", + "type": "string" + }, + "parameters": { + "example": {}, + "type": "object" + } + }, + "required": [ + "name", + "description", + "parameters" + ], + "type": "object" + }, + "type": { + "enum": [ + "function" + ], + "example": "function", + "type": "string" + } + }, + "required": [ + "type", + "function" + ], + "type": "object" + }, + "type": "array" + }, "thread_id": { "example": "string", "type": "string" @@ -87340,7 +87259,6 @@ "required": true, "type": "agent_user" }, - "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", @@ -87867,7 +87785,6 @@ "required": true, "type": "agent_user" }, - "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", @@ -89520,7 +89437,6 @@ "required": true, "type": "agent_user" }, - "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", @@ -90047,7 +89963,6 @@ "required": true, "type": "agent_user" }, - "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", @@ -94971,7 +94886,6 @@ "updated_at": "string", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" }, - "nullable": true, "properties": { "acl": { "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.", @@ -95748,7 +95662,6 @@ "required": true, "type": "agent_user" }, - "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", @@ -96275,7 +96188,6 @@ "required": true, "type": "agent_user" }, - "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", @@ -96578,7 +96490,6 @@ {} ], "items": { - "nullable": true, "type": "object" }, "nullable": true, @@ -99515,7 +99426,6 @@ "updated_at": "string", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" }, - "nullable": true, "properties": { "acl": { "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.", @@ -100292,7 +100202,6 @@ "required": true, "type": "agent_user" }, - "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", @@ -100819,7 +100728,6 @@ "required": true, "type": "agent_user" }, - "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", @@ -101122,7 +101030,6 @@ {} ], "items": { - "nullable": true, "type": "object" }, "nullable": true, @@ -105969,7 +105876,6 @@ "required": true, "type": "agent_user" }, - "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", @@ -106496,7 +106402,6 @@ "required": true, "type": "agent_user" }, - "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", @@ -108149,7 +108054,6 @@ "required": true, "type": "agent_user" }, - "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", @@ -108676,7 +108580,6 @@ "required": true, "type": "agent_user" }, - "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", @@ -113600,7 +113503,6 @@ "updated_at": "string", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" }, - "nullable": true, "properties": { "acl": { "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.", @@ -114377,7 +114279,6 @@ "required": true, "type": "agent_user" }, - "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", @@ -114904,7 +114805,6 @@ "required": true, "type": "agent_user" }, - "nullable": true, "properties": { "description": { "description": "Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", @@ -115207,7 +115107,6 @@ {} ], "items": { - "nullable": true, "type": "object" }, "nullable": true, diff --git a/src/archastro/platform/channels/api_chat_channel.py b/src/archastro/platform/channels/api_chat_channel.py index 4eedce6..0458607 100644 --- a/src/archastro/platform/channels/api_chat_channel.py +++ b/src/archastro/platform/channels/api_chat_channel.py @@ -1,6 +1,6 @@ # Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. # This file is auto-generated by @archastro/sdk-generator. Do not edit. -# Content hash: 81654b87b94d +# Content hash: 45505bffc4df from collections.abc import Callable from datetime import datetime @@ -715,12 +715,12 @@ async def join_team_transient( join_response = await channel.join(payload) return cls(channel, join_response) - # Join a user-scoped thread by ID + # Join a user-scoped thread by ID, optionally supplying local tools for a personal thread @staticmethod def topic_user_thread(thread_id: str) -> str: return f"api:chat:user:thread:{thread_id}" - # Join a user-scoped thread by ID + # Join a user-scoped thread by ID, optionally supplying local tools for a personal thread @classmethod async def join_user_thread( cls, @@ -731,6 +731,8 @@ async def join_user_thread( before_cursor: str | None = None, include_metadata: bool | None = None, limit: int | None = None, + local_tool_provider_id: str | None = None, + local_tools: list[dict[str, Any]] | None = None, ) -> "ApiChatChannel": topic = cls.topic_user_thread(thread_id) channel = socket.channel(topic) @@ -743,6 +745,10 @@ async def join_user_thread( payload["include_metadata"] = include_metadata if limit is not None: payload["limit"] = limit + if local_tool_provider_id is not None: + payload["local_tool_provider_id"] = local_tool_provider_id + if local_tools is not None: + payload["local_tools"] = local_tools join_response = await channel.join(payload) return cls(channel, join_response) diff --git a/src/archastro/platform/types/chat.py b/src/archastro/platform/types/chat.py index ab02785..908fcfb 100644 --- a/src/archastro/platform/types/chat.py +++ b/src/archastro/platform/types/chat.py @@ -1,7 +1,8 @@ # Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. # This file is auto-generated by @archastro/sdk-generator. Do not edit. -# Content hash: 506586700b5b +# Content hash: 43c3317ab780 +from typing import Any, Literal from pydantic import BaseModel, Field @@ -106,6 +107,25 @@ class ChatLoadMoreMessagesResponse(BaseModel): ) +class ChatLocalToolFunction(BaseModel): + """ + A function implemented by the client connected to a personal thread. + """ + + description: str + name: str + parameters: dict[str, Any] + + +class ChatLocalToolDefinition(BaseModel): + """ + An OpenAI-compatible local function definition supplied while joining a personal thread. + """ + + function: ChatLocalToolFunction + type: Literal["function"] + + class ChatMarkThreadReadResponse(BaseModel): """ Response returned after marking a chat thread as read. Confirms that the read marker was successfully recorded for the authenticated user. diff --git a/src/archastro/platform/types/threads.py b/src/archastro/platform/types/threads.py index c8fffef..68cd29a 100644 --- a/src/archastro/platform/types/threads.py +++ b/src/archastro/platform/types/threads.py @@ -1,6 +1,6 @@ # Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. # This file is auto-generated by @archastro/sdk-generator. Do not edit. -# Content hash: d7cef8b17ff6 +# Content hash: 7efd3b7c1931 from datetime import datetime from typing import Any, Literal @@ -127,7 +127,7 @@ class Thread(BaseModel): default=None, description="URL-safe slug for the thread, used in human-readable permalinks. `null` if not assigned.", ) - sub_threads: list[dict[str, Any] | None] | None = Field( + sub_threads: list[dict[str, Any]] | None = Field( default=None, description="Threads that are nested under this thread as replies to a parent message. Present only when sub-thread enrichment is requested.", ) diff --git a/src/archastro/platform/v1/resources/teams.py b/src/archastro/platform/v1/resources/teams.py index 346e851..34c9731 100644 --- a/src/archastro/platform/v1/resources/teams.py +++ b/src/archastro/platform/v1/resources/teams.py @@ -1,6 +1,6 @@ # Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. # This file is auto-generated by @archastro/sdk-generator. Do not edit. -# Content hash: 64601c00bb1d +# Content hash: 3816e2e1ff4d from __future__ import annotations @@ -530,7 +530,6 @@ class MemberListResponseDataItemAgentSourceSolutionCurrentSolutionTemplatesItemD participants: ( list[ MemberListResponseDataItemAgentSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContractParticipantsItem - | None ] | None ) = Field( @@ -780,7 +779,6 @@ class MemberListResponseDataItemAgentSourceSolutionSolutionTemplatesItemDetailsI participants: ( list[ MemberListResponseDataItemAgentSourceSolutionSolutionTemplatesItemDetailsInvokeContractParticipantsItem - | None ] | None ) = Field( @@ -2892,7 +2890,6 @@ class TeamThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrent participants: ( list[ TeamThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContractParticipantsItem - | None ] | None ) = Field( @@ -3150,7 +3147,6 @@ class TeamThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutio participants: ( list[ TeamThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContractParticipantsItem - | None ] | None ) = Field( @@ -3558,11 +3554,11 @@ class TeamThreadListResponseDataItem(BaseModel): default=None, description="Composite actor identifiers for all participants currently active in this thread. Present only when actor enrichment is requested.", ) - participating_agents: ( - list[TeamThreadListResponseDataItemParticipatingAgentsItem | None] | None - ) = Field( - default=None, - description="Expanded agent objects for all agents participating in this thread. Present only when agent enrichment is requested.", + participating_agents: list[TeamThreadListResponseDataItemParticipatingAgentsItem] | None = ( + Field( + default=None, + description="Expanded agent objects for all agents participating in this thread. Present only when agent enrichment is requested.", + ) ) role: str | None = Field( default=None, @@ -3580,7 +3576,7 @@ class TeamThreadListResponseDataItem(BaseModel): default=None, description="URL-safe slug for the thread, used in human-readable permalinks. `null` if not assigned.", ) - sub_threads: list[dict[str, Any] | None] | None = Field( + sub_threads: list[dict[str, Any]] | None = Field( default=None, description="Threads that are nested under this thread as replies to a parent message. Present only when sub-thread enrichment is requested.", ) diff --git a/src/archastro/platform/v1/resources/users.py b/src/archastro/platform/v1/resources/users.py index 9508a99..dceea08 100644 --- a/src/archastro/platform/v1/resources/users.py +++ b/src/archastro/platform/v1/resources/users.py @@ -1,6 +1,6 @@ # Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. # This file is auto-generated by @archastro/sdk-generator. Do not edit. -# Content hash: 76fffb92dd91 +# Content hash: dcaf6f16ffbe from __future__ import annotations @@ -1807,7 +1807,6 @@ class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrent participants: ( list[ UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContractParticipantsItem - | None ] | None ) = Field( @@ -2065,7 +2064,6 @@ class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutio participants: ( list[ UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContractParticipantsItem - | None ] | None ) = Field( @@ -2473,11 +2471,11 @@ class UserThreadListResponseDataItem(BaseModel): default=None, description="Composite actor identifiers for all participants currently active in this thread. Present only when actor enrichment is requested.", ) - participating_agents: ( - list[UserThreadListResponseDataItemParticipatingAgentsItem | None] | None - ) = Field( - default=None, - description="Expanded agent objects for all agents participating in this thread. Present only when agent enrichment is requested.", + participating_agents: list[UserThreadListResponseDataItemParticipatingAgentsItem] | None = ( + Field( + default=None, + description="Expanded agent objects for all agents participating in this thread. Present only when agent enrichment is requested.", + ) ) role: str | None = Field( default=None, @@ -2495,7 +2493,7 @@ class UserThreadListResponseDataItem(BaseModel): default=None, description="URL-safe slug for the thread, used in human-readable permalinks. `null` if not assigned.", ) - sub_threads: list[dict[str, Any] | None] | None = Field( + sub_threads: list[dict[str, Any]] | None = Field( default=None, description="Threads that are nested under this thread as replies to a parent message. Present only when sub-thread enrichment is requested.", ) diff --git a/tests/contract/channels/test_api_chat_channel.py b/tests/contract/channels/test_api_chat_channel.py index 71277b3..6398be5 100644 --- a/tests/contract/channels/test_api_chat_channel.py +++ b/tests/contract/channels/test_api_chat_channel.py @@ -1,6 +1,6 @@ # Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. # This file is auto-generated by @archastro/sdk-generator. Do not edit. -# Content hash: ddd9e94df7fe +# Content hash: a855958b5ea6 """ Contract tests for ApiChatChannel — generated from the channel spec. @@ -156,6 +156,17 @@ async def test_api_chat_channel_join_user_thread_joins_and_receives_contract_val before_cursor="test-value", include_metadata=True, limit=1, + local_tool_provider_id="test-id", + local_tools=[ + { + "function": { + "description": "test description", + "name": "test-name", + "parameters": {}, + }, + "type": "function", + } + ], ) assert isinstance(channel, ApiChatChannel) assert channel.join_response is not None @@ -177,6 +188,17 @@ async def test_api_chat_channel_join_user_thread_surfaces_server_error_reply_as_ before_cursor="test-value", include_metadata=True, limit=1, + local_tool_provider_id="test-id", + local_tools=[ + { + "function": { + "description": "test description", + "name": "test-name", + "parameters": {}, + }, + "type": "function", + } + ], )