diff --git a/specs/platform-openapi.json b/specs/platform-openapi.json index 289df4c..4f8d6be 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": { @@ -1580,6 +1617,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": { @@ -1605,6 +1643,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -1653,11 +1692,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 +1709,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 +1740,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 +1751,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 +1837,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 +1859,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 +1870,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 +1895,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 +1915,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 +1965,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 +1987,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 +2003,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 +2025,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 +2058,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 +2066,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -2024,12 +2091,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 +2113,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": { @@ -2073,6 +2143,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": { @@ -2098,6 +2169,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -2146,11 +2218,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 +2235,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 +2266,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 +2277,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 +2313,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 +2335,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 +2353,7 @@ "virtual_path": { "description": "Virtual filesystem path for this template config. `null` if not set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -2290,22 +2373,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 +2513,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 +2528,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" }, @@ -2445,21 +2536,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 +2607,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 +2745,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 +2813,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 +2961,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 +3009,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 +3038,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 +3068,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 +3447,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 +3470,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 +3518,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 +3541,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 +3554,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 +3572,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 +6556,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 +6585,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 +6648,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 +6661,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 +6691,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 +6706,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -6362,6 +6768,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 +7478,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 +7493,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -7220,7 +7633,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" } ], @@ -7422,7 +7835,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "participant": [ @@ -7433,6 +7846,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 +7861,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -7648,7 +8067,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 +8271,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "participant": [ @@ -7863,6 +8282,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 +8297,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -8078,7 +8503,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 +8906,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 +8921,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -8630,7 +9061,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" } ], @@ -8832,7 +9263,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "participant": [ @@ -8843,6 +9274,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 +9289,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -9058,7 +9495,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", @@ -9077,412 +9514,474 @@ ], "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.", + "ChatLocalToolDefinition": { + "description": "An OpenAI-compatible local function definition supplied while joining a personal thread.", "example": { - "success": true + "function": { + "description": "An example description.", + "name": "Example Name", + "parameters": {} + }, + "type": "function" }, "properties": { - "success": { - "description": "Indicates whether the read marker was successfully applied. Always `true` on success; errors are returned as channel error replies rather than a `false` value here.", - "example": true, - "type": "boolean" + "function": { + "$ref": "#/components/schemas/ChatLocalToolFunction" + }, + "type": { + "enum": [ + "function" + ], + "example": "function", + "type": "string" } }, "required": [ - "success" + "type", + "function" ], "type": "object" }, - "ChatMember": { - "description": "A participant in a chat thread, which may be either a human user or an AI agent. Exactly one of `user` or `agent` is populated depending on `type`.", + "ChatLocalToolFunction": { + "description": "A function implemented by the client connected to a personal thread.", "example": { - "agent": { - "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" - }, - "membership_type": "owner", - "type": "user", - "user": { - "alias": "jdoe", - "app": "dap_0aBcDeFgHiJkLmNoPqRsTu", - "app_name": "Example Name", - "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", - "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", - "sandbox_name": "Example Name" - } + "description": "An example description.", + "name": "Example Name", + "parameters": {} }, "properties": { - "agent": { - "$ref": "#/components/schemas/Agent", - "description": "Full agent object for this member. Populated when `type` is `\"agent\"`; `null` for user members." - }, - "membership_type": { - "description": "Role of this member within the thread. Common values are `\"owner\"` and `\"member\"`. `null` when the membership type is not applicable.", - "example": "owner", + "description": { + "example": "An example description.", "type": "string" }, - "type": { - "description": "Kind of participant. One of `\"user\"` (a human user) or `\"agent\"` (an AI agent).", - "example": "user", + "name": { + "example": "Example Name", "type": "string" }, - "user": { - "$ref": "#/components/schemas/User", - "description": "Full user object for this member. Populated when `type` is `\"user\"`; `null` for agent members." + "parameters": { + "example": {}, + "type": "object" } }, "required": [ - "type" + "name", + "description", + "parameters" ], "type": "object" }, - "ChatMessageListResponse": { - "description": "Response returned when listing the messages of a joined chat thread. Contains the set of messages currently loaded for the thread.", + "ChatMarkThreadReadResponse": { + "description": "Response returned after marking a chat thread as read. Confirms that the read marker was successfully recorded for the authenticated user.", "example": { - "messages": [ - { - "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": "string", - "visibility": "default" - } - ] + "success": true }, "properties": { - "messages": { - "description": "Ordered array of message objects currently loaded for the thread, from oldest to newest. Use the `load_more_messages` channel message to fetch earlier pages.", - "items": { - "$ref": "#/components/schemas/Message" - }, - "type": "array" + "success": { + "description": "Indicates whether the read marker was successfully applied. Always `true` on success; errors are returned as channel error replies rather than a `false` value here.", + "example": true, + "type": "boolean" } }, "required": [ - "messages" + "success" ], "type": "object" }, - "ChatPostMessageResponse": { - "description": "Response returned after successfully posting a message to a chat thread. Contains the persisted message object echoed back to the sender.", + "ChatMember": { + "description": "A participant in a chat thread, which may be either a human user or an AI agent. Exactly one of `user` or `agent` is populated depending on `type`.", "example": { - "message": { + "agent": { + "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" + }, + "membership_type": "owner", + "type": "user", + "user": { + "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": { + "agent": { + "$ref": "#/components/schemas/Agent", + "description": "Full agent object for this member. Populated when `type` is `\"agent\"`; `null` for user members." + }, + "membership_type": { + "description": "Role of this member within the thread. Common values are `\"owner\"` and `\"member\"`. `null` when the membership type is not applicable.", + "example": "owner", + "type": "string" + }, + "type": { + "description": "Kind of participant. One of `\"user\"` (a human user) or `\"agent\"` (an AI agent).", + "example": "user", + "type": "string" + }, + "user": { + "$ref": "#/components/schemas/User", + "description": "Full user object for this member. Populated when `type` is `\"user\"`; `null` for agent members." + } + }, + "required": [ + "type" + ], + "type": "object" + }, + "ChatMessageListResponse": { + "description": "Response returned when listing the messages of a joined chat thread. Contains the set of messages currently loaded for the thread.", + "example": { + "messages": [ + { + "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" + } + ] + }, + "properties": { + "messages": { + "description": "Ordered array of message objects currently loaded for the thread, from oldest to newest. Use the `load_more_messages` channel message to fetch earlier pages.", + "items": { + "$ref": "#/components/schemas/Message" + }, + "type": "array" + } + }, + "required": [ + "messages" + ], + "type": "object" + }, + "ChatPostMessageResponse": { + "description": "Response returned after successfully posting a message to a chat thread. Contains the persisted message object echoed back to the sender.", + "example": { + "message": { "acl": { "add": [ { @@ -9615,7 +10114,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" } }, @@ -10006,6 +10505,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 +10520,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -10155,7 +10660,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" } ], @@ -10357,7 +10862,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "participant": [ @@ -10368,6 +10873,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 +10888,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -10583,7 +11094,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 +12181,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,6 +12289,558 @@ ], "type": "object" }, + "DomainEvent": { + "description": "A domain event with stable attribution fields and an event-specific payload.", + "example": { + "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" + }, + "properties": { + "agent": { + "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "created_at": { + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "type": "string" + }, + "event_name": { + "example": "Example Name", + "type": "string" + }, + "id": { + "example": "string", + "type": "string" + }, + "idempotency_key": { + "example": "string", + "type": "string" + }, + "org": { + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "payload": { + "description": "Opaque event-specific JSON. Use event_name to select the expected payload schema.", + "example": {}, + "type": "object" + }, + "sandbox": { + "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "team": { + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "user": { + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + } + }, + "required": [ + "id", + "event_name", + "payload", + "created_at" + ], + "type": "object" + }, + "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", + "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": { + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "type": "string" + }, + "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": { + "example": "string", + "type": "string" + }, + "last_overflow_at": { + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "type": "string" + }, + "leased_count": { + "example": 1, + "type": "integer" + }, + "max_pending_events": { + "example": 1, + "type": "integer" + }, + "name": { + "example": "Example Name", + "type": "string" + }, + "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": [ + "active", + "paused" + ], + "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", + "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" + }, + "EventSubscriptionClaim": { + "description": "Result of atomically claiming the head delivery.", + "example": { + "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", + "receipt_handle": "string", + "receive_count": 1, + "sequence": 1 + } + ], + "dropped_events_total": 1, + "dropped_through_position": 1, + "has_more": true, + "queue_epoch": 1 + }, + "properties": { + "data": { + "items": { + "$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", + "has_more", + "queue_epoch", + "dropped_events_total", + "dropped_through_position" + ], + "type": "object" + }, + "EventSubscriptionDelivery": { + "description": "A domain event leased from a subscription queue.", + "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", + "receipt_handle": "string", + "receive_count": 1, + "sequence": 1 + }, + "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" + }, + "receipt_handle": { + "example": "string", + "type": "string" + }, + "receive_count": { + "example": 1, + "type": "integer" + }, + "sequence": { + "example": 1, + "type": "integer" + } + }, + "required": [ + "delivery_id", + "sequence", + "receipt_handle", + "lease_expires_at", + "receive_count", + "event" + ], + "type": "object" + }, + "EventSubscriptionHead": { + "description": "A non-reserving view of the queue head.", + "example": { + "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": { @@ -12021,36 +13123,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" } }, @@ -12409,6 +13518,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 +13942,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 +13959,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 +13974,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 +14000,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 +14011,7 @@ "width": { "description": "Width of this variant in pixels. `null` if not recorded.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -12994,7 +14123,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 +14282,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "root_message_id": "string", @@ -13161,13 +14290,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 +14341,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 +14351,7 @@ "embedded" ], "example": "cli", + "nullable": true, "type": "string" }, "attachments": { @@ -13200,17 +14364,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 +14391,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 +14402,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 +14415,7 @@ "org": { "description": "ID of the organization that owns this message (`org_...`).", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "reactions": { @@ -13260,6 +14428,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 +14444,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 +14593,10 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, + "nullable": true, "type": "object" }, "root_message_id": { @@ -13436,27 +14608,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 +15019,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 +15034,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -13889,7 +15220,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" } ], @@ -14202,6 +15533,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 +15784,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 +15807,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 +15883,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 +15899,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 +15948,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 +16021,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 +16047,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 +16110,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 +16166,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,6 +16348,7 @@ "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": { @@ -14747,6 +16356,7 @@ "items": { "$ref": "#/components/schemas/AutomationParticipantSlot" }, + "nullable": true, "type": "array" }, "prefills": { @@ -14782,13 +16392,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 +16873,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 +16959,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 +16992,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 +17001,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 +17041,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 +17052,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 +17149,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 +17212,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 +17241,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 +17252,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 +17478,7 @@ "category_keys": [ "string" ], - "created_at": "2024-01-01T00:00:00Z", + "created_at": "string", "description": "An example description.", "events": {}, "id": "id_0aBcDeFgHiJkLmNoPqRsTu", @@ -15885,7 +17528,7 @@ "virtual_path": "string" } ], - "updated_at": "2024-01-01T00:00:00Z", + "updated_at": "string", "upgrade_available": true, "virtual_path": "string" }, @@ -15902,13 +17545,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 +17567,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 +17578,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 +17603,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 +17655,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 +17671,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 +17693,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 +17705,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 +17716,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 +17945,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 +17977,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 +18294,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 +18309,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -16643,8 +18330,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 +18472,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 +18606,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -16817,6 +18636,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 +18653,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 +18665,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 +18680,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 +18731,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 +18779,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 +18831,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 +18875,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 +18893,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 +19130,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 +19174,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 +19186,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 +19197,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 +19215,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 +19467,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 +19482,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 +19705,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 +19734,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 +19749,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 +19996,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 +20011,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -17893,7 +20072,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 +20082,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 +20223,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "participant": [ @@ -18055,6 +20234,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 +20249,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -18270,9 +20455,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 +20465,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 +20487,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 +20502,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" }, @@ -18318,21 +20510,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 +20581,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 +20631,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 +20662,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 +20694,7 @@ "example": { "key": "value" }, + "nullable": true, "type": "object" }, "muted": { @@ -18461,11 +20705,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.", @@ -18499,16 +20885,19 @@ "items": { "$ref": "#/components/schemas/Agent" }, + "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 +20907,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": { @@ -18528,6 +20918,7 @@ "items": { "type": "object" }, + "nullable": true, "type": "array" }, "tags": { @@ -18544,32 +20935,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 +21245,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 +21256,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 +21285,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 +21345,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 +21367,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 +21385,7 @@ "virtual_path": { "description": "Virtual filesystem path for this template config. `null` if not set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -18992,6 +21401,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 +21416,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" }, @@ -19009,21 +21424,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 +21495,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 +22434,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 +22582,7 @@ }, "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "template_upgrade_available": true, - "updated_at": "2024-01-01T00:00:00Z", + "updated_at": "string", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" }, "properties": { @@ -20155,6 +22616,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -20305,23 +22767,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 +22796,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 +22826,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 +22984,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 +23059,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 +23081,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 +23092,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 +23117,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 +23137,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 +23187,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 +23209,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 +23225,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 +23247,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 +23280,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 +23288,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -20818,12 +23313,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 +23335,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": { @@ -20867,6 +23365,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": { @@ -20892,6 +23391,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -20940,11 +23440,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 +23457,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 +23488,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 +23499,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 +23585,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 +23607,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 +23618,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 +23643,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 +23663,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 +23713,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 +23735,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 +23751,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 +23773,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 +23806,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 +23814,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -21311,12 +23839,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 +23861,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": { @@ -21360,6 +23891,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": { @@ -21385,6 +23917,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -21433,11 +23966,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 +23983,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 +24014,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 +24025,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 +24061,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 +24083,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 +24101,7 @@ "virtual_path": { "description": "Virtual filesystem path for this template config. `null` if not set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -21577,22 +24121,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 +24261,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 +24276,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" }, @@ -21732,21 +24284,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 +24355,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 +31588,7 @@ "description": "An example description.", "is_unlisted": true, "key": "string", + "kind": "personal", "members": [ { "id": "string", @@ -29027,6 +31626,7 @@ "description": "An example description.", "is_unlisted": true, "key": "string", + "kind": "personal", "members": [ { "id": "string", @@ -29071,6 +31671,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 +31767,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 +33189,9 @@ }, "401": { "description": "Unauthorized" + }, + "403": { + "description": "Forbidden — app scope required" } }, "summary": "List available AI models", @@ -31692,6 +34304,7 @@ "full_name": "Example Name", "invite_code": "string", "password": "string", + "set_org": true, "team_invite": "string", "timezone": "America/New_York" }, @@ -31721,6 +34334,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 +34406,7 @@ "email": "user@example.com", "full_name": "Example Name", "redirect_uri": "https://example.com", + "set_org": true, "timezone": "America/New_York" }, "properties": { @@ -31811,6 +34430,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 +34482,8 @@ "schema": { "example": { "email": "user@example.com", - "redirect_uri": "https://example.com" + "redirect_uri": "https://example.com", + "set_org": true }, "properties": { "email": { @@ -31870,6 +34495,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 +38618,38 @@ ] } }, - "/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.", - "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.", + "receipt_handle": { + "description": "Opaque handle returned by claim.", "example": "string", "type": "string" - }, - "url": { - "description": "Source URL for link/site extraction.", - "example": "https://example.com", - "type": "string" } }, "required": [ - "destination_kind" + "receipt_handle" ], "type": "object" } @@ -36067,46 +38658,49 @@ "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\"`." + "204": { + "description": "No content" }, - "404": { - "description": "File not found" + "401": { + "description": "Unauthorized" }, - "422": { - "description": "Invalid parameters; Unsupported content type" + "404": { + "description": "Event subscription delivery not found" }, - "502": { - "description": "Service unavailable" + "409": { + "description": "The delivery lease is no longer current" } }, - "summary": "Start an extraction", + "summary": "Acknowledge a claimed event", "x-auth": [ "publishable_key", "bearer" ] } }, - "/api/v1/extractions/{extraction}": { + "/api/v1/event_subscriptions": { "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": "Lists the subscriptions visible to the caller, with current queue counters.", + "operationId": "get_api_v1_event_subscriptions", "parameters": [ { - "description": "Extraction ID (`ext_...`).", - "example": "string", - "in": "path", - "name": "extraction", - "required": true, + "description": "Page number, starting at 1.", + "example": 1, + "in": "query", + "name": "page", + "required": false, "schema": { - "type": "string" + "type": "integer" + } + }, + { + "description": "Subscriptions per page, from 1 through 100.", + "example": 1, + "in": "query", + "name": "per_page", + "required": false, + "schema": { + "type": "integer" } } ], @@ -36115,289 +38709,87 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Extraction" + "$ref": "#/components/schemas/EventSubscriptionPage" } } }, - "description": "The extraction job." + "description": "Subscriptions visible to this caller." }, - "404": { - "description": "Extraction not found" + "401": { + "description": "Unauthorized" + }, + "422": { + "description": "Invalid parameters" } }, - "summary": "Retrieve an extraction", + "summary": "List domain-event subscriptions", "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", + "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": { - "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" + "event_names": [ + "Example Name" + ], + "max_pending_events": 1, + "name": "Example Name", + "retention_seconds": 1, + "status": "active", + "visibility_timeout_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" - ], - "items": { - "type": "string" - }, - "type": "array" - }, - "principal": { - "description": "The identifier of the principal. A string ID for `\"user\"`, `\"team\"`, `\"org\"`, and `\"agent\"` types; one of `\"admin\"`, `\"member\"`, or `\"viewer\"` for `\"org_role\"`; omit entirely when `principal_type` is `\"everyone\"`.", - "example": "string", - "type": "string" - }, - "principal_type": { - "description": "The kind of principal receiving the grant. One of `\"user\"`, `\"team\"`, `\"org\"`, `\"org_role\"`, `\"agent\"`, or `\"everyone\"`.", - "example": "user", - "type": "string" - } - }, - "required": [ - "principal_type", - "actions" - ], - "type": "object" - }, - "type": "array" - }, - "grants": { - "description": "Replace mode: the complete new list of grants that replaces all existing entries. Send an empty array (`[]`) to clear all grants. Cannot be combined with `add` or `remove`.", - "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" - }, - "type": "array" - }, - "principal": { - "description": "The identifier of the principal. A string ID for `\"user\"`, `\"team\"`, `\"org\"`, and `\"agent\"` types; one of `\"admin\"`, `\"member\"`, or `\"viewer\"` for `\"org_role\"`; omit entirely when `principal_type` is `\"everyone\"`.", - "example": "string", - "type": "string" - }, - "principal_type": { - "description": "The kind of principal receiving the grant. One of `\"user\"`, `\"team\"`, `\"org\"`, `\"org_role\"`, `\"agent\"`, or `\"everyone\"`.", - "example": "user", - "type": "string" - } - }, - "required": [ - "principal_type", - "actions" - ], - "type": "object" - }, - "type": "array" - }, - "remove": { - "description": "Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`.", - "example": [ - { - "principal": "string", - "principal_type": "user" - } - ], - "items": { - "description": "Identifies a principal to be removed from an access-control list.", - "example": { - "principal": "string", - "principal_type": "user" - }, - "properties": { - "principal": { - "description": "The identifier of the principal to remove. A string ID for `\"user\"`, `\"team\"`, `\"org\"`, and `\"agent\"` types; one of `\"admin\"`, `\"member\"`, or `\"viewer\"` for `\"org_role\"`. Omit when `principal_type` is `\"everyone\"`.", - "example": "string", - "type": "string" - }, - "principal_type": { - "description": "The kind of principal to remove. One of `\"user\"`, `\"team\"`, `\"org\"`, `\"org_role\"`, `\"agent\"`, or `\"everyone\"`.", - "example": "user", - "type": "string" - } - }, - "required": [ - "principal_type" - ], - "type": "object" - }, - "type": "array" - } + "event_names": { + "description": "Exact event names to receive.", + "example": [ + "Example Name" + ], + "items": { + "type": "string" }, - "type": "object" - }, - "agent": { - "description": "Agent ID (`agi_...`) to associate with this file. When provided, the file's organization is derived from the agent.", - "example": "string", - "type": "string" - }, - "content_type": { - "description": "MIME type of the file, e.g. `\"image/png\"` or `\"application/pdf\"`.", - "example": "application/json", - "type": "string" - }, - "data": { - "description": "Base64-encoded binary content of the file to upload.", - "example": "string", - "type": "string" + "type": "array" }, - "filename": { - "description": "Original filename including extension, e.g. `\"avatar.png\"`.", - "example": "string", - "type": "string" + "max_pending_events": { + "description": "Queue cap. Defaults to 100; maximum 1000.", + "example": 1, + "type": "integer" }, - "org": { - "description": "Organization ID (`org_...`) to associate with this file. Optional; defaults to the viewer's organization when omitted.", - "example": "string", + "name": { + "description": "Customer-defined subscription name.", + "example": "Example Name", "type": "string" }, - "share": { - "description": "When `true`, marks the file publicly shareable and returns a stable, non-expiring `share_url` fetchable without authentication. Only image content types can be shared.", - "example": true, - "type": "boolean" + "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" }, - "team": { - "description": "Team ID (`tem_...`) that owns this file. Takes precedence over `user` when both are provided.", - "example": "string", + "status": { + "description": "Initial status. Defaults to active.", + "enum": [ + "active", + "paused" + ], + "example": "active", "type": "string" }, - "user": { - "description": "User ID (`usr_...`) that owns this file. Defaults to the authenticated user when neither `user` nor `team` is specified.", - "example": "string", - "type": "string" + "visibility_timeout_seconds": { + "description": "Default claim lease in seconds. Defaults to 300.", + "example": 1, + "type": "integer" } }, "required": [ - "data", - "content_type", - "filename" + "name", + "event_names" ], "type": "object" } @@ -36406,77 +38798,165 @@ "required": true }, "responses": { - "201": { + "200": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/StorageFile" + "$ref": "#/components/schemas/EventSubscription" } } }, - "description": "The newly created file, including a signed download URL." + "description": "The new volatile subscription." }, "401": { "description": "Unauthorized" }, - "403": { - "description": "Forbidden - app scope required" - }, "422": { - "description": "Validation failed or invalid base64" + "description": "Invalid parameters; Validation failed" } }, - "summary": "Upload a file", + "summary": "Create a domain-event subscription", "x-auth": [ "publishable_key", "bearer" ] } }, - "/api/v1/files/{file}": { - "patch": { - "description": "Updates mutable fields of an existing file. Only the fields you supply are\nchanged; omitted fields retain their current values. The file's stored content\nand `content_type` cannot be changed after creation.\n\nThis endpoint is the companion to `share: true` on file upload: the same\ncredential that granted public sharing can revoke it here with `share: false`\n(or grant it later with `share: true`; only image content types can be\nshared, and re-enabling sharing reactivates any previously issued share\nURLs). App scope is derived from the authenticated viewer, matching upload.\n\nA file that exists but is not visible to the current viewer returns `404`\nrather than `403` to avoid revealing the file's existence.\n", - "operationId": "patch_api_v1_files__file", + "/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": "File ID (`fil_...`) of the file to update.", + "description": "Subscription ID (`esub_...`).", "example": "string", "in": "path", - "name": "file", + "name": "subscription", "required": true, "schema": { "type": "string" } } ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "example": { - "filename": "string", - "provider_metadata": { - "key": "value" - }, - "share": true + "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 one subscription and its current queue counters.", + "operationId": "get_api_v1_event_subscriptions__subscription", + "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/EventSubscription" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "404": { + "description": "Event subscription not found" + } + }, + "summary": "Get a domain-event subscription", + "x-auth": [ + "publishable_key", + "bearer" + ] + }, + "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": { + "event_names": [ + "Example Name" + ], + "max_pending_events": 1, + "name": "Example Name", + "retention_seconds": 1, + "status": "active", + "visibility_timeout_seconds": 1 }, "properties": { - "filename": { - "description": "New name for the file, including extension, e.g. `\"report_v2.pdf\"`. Omit to leave the current filename unchanged.", - "example": "string", + "event_names": { + "example": [ + "Example Name" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "max_pending_events": { + "example": 1, + "type": "integer" + }, + "name": { + "example": "Example Name", "type": "string" }, - "provider_metadata": { - "description": "Arbitrary key-value map of provider-specific metadata to store alongside the file. Replaces the entire existing `provider_metadata` map. Omit to leave it unchanged.", - "example": { - "key": "value" - }, - "type": "object" + "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" }, - "share": { - "description": "Set `true` to mark the file publicly shareable via its stable `share_url` (image content types only), or `false` to revoke public sharing. Re-enabling sharing reactivates any previously issued share URLs for the file. Omit to leave sharing unchanged.", - "example": true, - "type": "boolean" + "status": { + "enum": [ + "active", + "paused" + ], + "example": "active", + "type": "string" + }, + "visibility_timeout_seconds": { + "example": 1, + "type": "integer" } }, "type": "object" @@ -36490,97 +38970,127 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/StorageFile" + "$ref": "#/components/schemas/EventSubscription" } } }, - "description": "The updated file, including a signed download URL." + "description": "Successful response" }, "401": { "description": "Unauthorized" }, - "403": { - "description": "Forbidden - app scope required" - }, "404": { - "description": "File not found" + "description": "Event subscription not found" }, "422": { - "description": "Validation failed" + "description": "Invalid parameters; Validation failed" } }, - "summary": "Update a file", + "summary": "Update a domain-event subscription", "x-auth": [ "publishable_key", "bearer" ] } }, - "/api/v1/files/{file}/avatar": { - "get": { - "description": "Returns the raw image bytes for an agent's profile picture identified by `file`.\nThis endpoint is designed for integration partners (such as Slack) that fetch\navatar URLs via plain GET requests without bearer token support. Authorization\nis performed via a short, stable capability `token` rather than an HTTP header.\n\nThe `token` is an HMAC-based capability tied to the file ID. It does not expire,\nbut it is invalidated when the agent's profile picture is replaced or the agent is\ndeleted — shared caches may continue serving the old image until the\n`Cache-Control` max-age of one hour elapses. The endpoint never redirects to\na signed storage URL; bytes are served inline so behavior is consistent across\nstorage backends.\n\nAll failure modes — invalid file ID, invalid token, file not currently referenced\nas an agent avatar — return a uniform `404` to avoid acting as an existence oracle.\n", - "operationId": "get_api_v1_files__file_avatar", + "/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": "File ID of the agent's profile picture (`fil_...`). Must be currently set as an agent's profile picture within the same app.", + "description": "Subscription ID (`esub_...`).", "example": "string", "in": "path", - "name": "file", - "required": true, - "schema": { - "type": "string" - } - }, - { - "description": "HMAC capability token authorizing access to this specific file. Obtained from the avatar URL minted when the profile picture was set.", - "example": "string", - "in": "query", - "name": "token", + "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": { + "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": { - "format": "binary", - "type": "string" + "$ref": "#/components/schemas/EventSubscriptionClaim" } } }, - "description": "Raw image bytes of the agent avatar, served with the file's original content type." + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" }, "404": { - "description": "Not found" + "description": "Event subscription not found" + }, + "422": { + "description": "Invalid parameters; Validation failed" } }, - "summary": "Fetch an agent avatar image" + "summary": "Claim events from a subscription", + "x-auth": [ + "publishable_key", + "bearer" + ] } }, - "/api/v1/files/{file}/org_logo": { + "/api/v1/event_subscriptions/{subscription}/head": { "get": { - "description": "Returns the raw image bytes for an organization's logo identified by `file`.\nThis endpoint backs the `org_logo.url` field of catalog payloads (such as\n`GET /api/v1/solutions`), which anonymous consumers — the public marketplace's\npage cache, OpenGraph scrapers — may hold far longer than a signed storage URL\nlives. Authorization is performed via a short, stable capability `token` rather\nthan an HTTP header, so the URL never expires.\n\nThe `token` is an HMAC-based capability tied to the file ID. It does not expire,\nbut it is invalidated when the org's logo is replaced or removed — shared caches\nmay continue serving the old image until the `Cache-Control` max-age of one hour\nelapses. The endpoint never redirects to a signed storage URL; bytes are served\ninline so behavior is consistent across storage backends.\n\nAll failure modes — invalid file ID, invalid token, file not currently referenced\nas an org logo — return a uniform `404` to avoid acting as an existence oracle.\n", - "operationId": "get_api_v1_files__file_org_logo", + "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": "File ID of the org's logo (`fil_...`). Must be currently set as an organization's logo within the same app.", + "description": "Subscription ID (`esub_...`).", "example": "string", "in": "path", - "name": "file", - "required": true, - "schema": { - "type": "string" - } - }, - { - "description": "HMAC capability token authorizing access to this specific file. Obtained from the `org_logo.url` minted when the logo was serialized.", - "example": "string", - "in": "query", - "name": "token", + "name": "subscription", "required": true, "schema": { "type": "string" @@ -36590,43 +39100,69 @@ "responses": { "200": { "content": { - "*/*": { + "application/json": { "schema": { - "format": "binary", - "type": "string" + "$ref": "#/components/schemas/EventSubscriptionHead" } } }, - "description": "Raw image bytes of the org logo, served with the file's original content type." + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" }, "404": { - "description": "Not found" + "description": "Event subscription not found" } }, - "summary": "Fetch an org logo image" + "summary": "Peek at the head of a subscription queue", + "x-auth": [ + "publishable_key", + "bearer" + ] } }, - "/api/v1/files/{file}/share": { + "/api/v1/event_subscriptions/{subscription}/queue": { "get": { - "description": "Returns the raw image bytes for a file that was explicitly shared for public\naccess, identified by `file`. This endpoint is designed for consumers that hold\na URL far longer than a signed storage URL lives — GitHub PR bodies (whose camo\nimage proxy re-fetches from the origin URL), wikis, and issue trackers — and\nfetch it via plain GET requests without bearer token support. Authorization is\nperformed via a short, stable capability `token` rather than an HTTP header.\n\nThe `token` is an HMAC-based capability tied to the file ID. It does not expire,\nbut it is invalidated when sharing is turned off for the file (`share: false` on\nthe file update endpoint) or the file is deleted — shared caches may continue\nserving the bytes until the `Cache-Control` max-age of one hour elapses. The\nendpoint never redirects to a signed storage URL; bytes are served inline so\nbehavior is consistent across storage backends. Only image content types are\nserved.\n\nAll failure modes — invalid file ID, invalid token, file not currently shared —\nreturn a uniform `404` to avoid acting as an existence oracle.\n", - "operationId": "get_api_v1_files__file_share", + "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": "File ID of the shared file (`fil_...`). The file must currently be marked as publicly shared.", + "description": "Subscription ID (`esub_...`).", "example": "string", "in": "path", - "name": "file", + "name": "subscription", "required": true, "schema": { "type": "string" } }, { - "description": "HMAC capability token authorizing access to this specific file. Obtained from the `share_url` returned when the file was uploaded with `share: true`.", + "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": "token", - "required": true, + "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" } @@ -36635,80 +39171,102 @@ "responses": { "200": { "content": { - "*/*": { + "application/json": { "schema": { - "format": "binary", - "type": "string" + "$ref": "#/components/schemas/EventSubscriptionQueue" } } }, - "description": "Raw image bytes of the shared file, served with the file's original content type." + "description": "Successful response" }, - "404": { - "description": "Not found" - } - }, - "summary": "Fetch a publicly shared file" - } - }, - "/api/v1/installation_sources/{source}": { - "delete": { - "description": "Detaches and permanently deletes a source from an installation. This action\ncannot be undone; the source and its associated content will no longer be\navailable to the installation's agent.\n\nThis endpoint requires an app-scoped token. You may identify the target\nindirectly by providing only the `source` ID — the installation is resolved\nautomatically from the source record. Providing `installation` explicitly\nis also accepted and may be more efficient.\n", - "operationId": "delete_api_v1_installation_sources__source", - "parameters": [ - { - "description": "Source ID (`cso_...`) of the source to remove.", - "example": "string", - "in": "path", - "name": "source", - "required": true, - "schema": { - "type": "string" - } - } - ], - "responses": { - "204": { - "description": "No content" + "400": { + "description": "Invalid cursor" }, "401": { "description": "Unauthorized" }, - "403": { - "description": "Forbidden - app scope required" - }, "404": { - "description": "Installation or source not found" + "description": "Event subscription not found" } }, - "summary": "Remove a source from an installation", + "summary": "Read a subscription queue", "x-auth": [ "publishable_key", "bearer" ] } }, - "/api/v1/invites/accept": { + "/api/v1/extractions": { "post": { - "description": "Accepts an invite on behalf of the authenticated user and adds them to the\nassociated team or thread. The invite `key` is passed in the request body\nrather than the URL so it never appears in access logs, `Referer` headers,\nor error-reporter URL captures.\n\nThis endpoint requires an authenticated end-user session. S2S secret-key\ntokens and unauthenticated requests are rejected with `401`. If the\nauthenticated user is already a member of the invite's target, the request\nreturns `409`. Both per-IP and per-user rate limits apply; exceeding either\nreturns `429`.\n", - "operationId": "post_api_v1_invites_accept", + "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": { - "key": "string" + "agent": "string", + "destination_kind": "config", + "destination_path": "string", + "file": "string", + "max_pages": 1, + "mode": "link", + "org": "string", + "url": "https://example.com" }, "properties": { - "key": { - "description": "Opaque invite key identifying the invite to accept. Obtained from an invite link or a previous invite creation response.", + "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": [ - "key" + "destination_kind" ], "type": "object" } @@ -36717,121 +39275,47 @@ "required": true }, "responses": { - "200": { + "201": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UserInvite" + "$ref": "#/components/schemas/Extraction" } } }, - "description": "The accepted invite, including its ID, key, metadata, optional thread scope, creator, and creation timestamp." - }, - "401": { - "description": "Unauthorized" - }, - "403": { - "description": "Forbidden" + "description": "The extraction job. Document extraction returns `201` with `state: \"done\"`; link/site extraction returns `202` with `state: \"running\"`." }, "404": { - "description": "Invite not found" - }, - "409": { - "description": "Conflict" + "description": "File not found" }, "422": { - "description": "Validation failed" + "description": "Invalid parameters; Unsupported content type" }, - "429": { - "description": "Too many requests" + "502": { + "description": "Service unavailable" } }, - "summary": "Accept an invite", + "summary": "Start an extraction", "x-auth": [ "publishable_key", "bearer" ] } }, - "/api/v1/knowledge_documents": { + "/api/v1/extractions/{extraction}": { "get": { - "description": "Returns a paginated list of context documents visible to the authenticated\ncaller within the scoped app. Results are ordered by creation time\ndescending.\n\nUse `q` for a case-insensitive title prefix search. Use `source`,\n`installation`, or `agent` to narrow results to documents belonging to\nspecific sources, installations, or agents. Multiple values within each\nfilter are treated as OR conditions. Filters may be combined.\n\nThe response includes page-level metadata so you can navigate through\nlarge result sets without cursor tokens.\n", - "operationId": "get_api_v1_knowledge_documents", + "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": "Page number to return. Defaults to 1.", - "example": 1, - "in": "query", - "name": "page", - "required": false, - "schema": { - "type": "integer" - } - }, - { - "description": "Number of documents per page. Defaults to 25.", - "example": 1, - "in": "query", - "name": "page_size", - "required": false, - "schema": { - "type": "integer" - } - }, - { - "description": "Case-insensitive prefix filter applied to the document title.", + "description": "Extraction ID (`ext_...`).", "example": "string", - "in": "query", - "name": "q", - "required": false, + "in": "path", + "name": "extraction", + "required": true, "schema": { "type": "string" } - }, - { - "description": "Return only documents belonging to these source IDs (`cso_...`). Multiple values are OR'd.", - "example": [ - "string" - ], - "in": "query", - "name": "source", - "required": false, - "schema": { - "items": { - "type": "string" - }, - "type": "array" - } - }, - { - "description": "Return only documents belonging to these installation IDs. Multiple values are OR'd.", - "example": [ - "string" - ], - "in": "query", - "name": "installation", - "required": false, - "schema": { - "items": { - "type": "string" - }, - "type": "array" - } - }, - { - "description": "Return only documents owned by these agent IDs. Multiple values are OR'd.", - "example": [ - "string" - ], - "in": "query", - "name": "agent", - "required": false, - "schema": { - "items": { - "type": "string" - }, - "type": "array" - } } ], "responses": { @@ -36839,258 +39323,427 @@ "content": { "application/json": { "schema": { - "description": "Paginated list of context documents for the current page.", - "example": { - "data": [ + "$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": [ { - "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", - "content_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", - "created_at": "2024-01-01T00:00:00Z", - "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", - "id": "cdo_0aBcDeFgHiJkLmNoPqRsTu", - "metadata": { - "key": "value" - }, - "source": "cso_0aBcDeFgHiJkLmNoPqRsTu", - "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", - "title": "Example Title", - "total_lines": 1, - "total_size": 2048, - "updated_at": "2024-01-01T00:00:00Z", - "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" + "actions": [ + "read", + "write" + ], + "principal": "string", + "principal_type": "user" } ], - "has_next": true, - "has_prev": true, - "page": 1, - "page_size": 1, - "total_entries": 1, - "total_pages": 1 - }, - "properties": { - "data": { - "description": "Array of context document objects for the current page.", - "example": [ - { - "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", - "content_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", - "created_at": "2024-01-01T00:00:00Z", - "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", - "id": "cdo_0aBcDeFgHiJkLmNoPqRsTu", - "metadata": { - "key": "value" - }, - "source": "cso_0aBcDeFgHiJkLmNoPqRsTu", - "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", - "title": "Example Title", - "total_lines": 1, - "total_size": 2048, - "updated_at": "2024-01-01T00:00:00Z", - "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" + "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" } ], - "items": { - "description": "A context document stored within a context source. Carries metadata and size information only; retrieve the full text content via the `/content` endpoint.\n", - "example": { - "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", - "content_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", - "created_at": "2024-01-01T00:00:00Z", - "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", - "id": "cdo_0aBcDeFgHiJkLmNoPqRsTu", - "metadata": { - "key": "value" - }, - "source": "cso_0aBcDeFgHiJkLmNoPqRsTu", - "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", - "title": "Example Title", - "total_lines": 1, - "total_size": 2048, - "updated_at": "2024-01-01T00:00:00Z", - "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" - }, - "properties": { - "agent": { - "description": "ID of the agent that owns this document (`agi_...`). `null` if owned by a user or team.", - "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "content_hash": { - "description": "Lowercase-hex sha256 of the document's full text, covering content only — not `title` or `metadata`. Compare it against a hash of your local copy to decide whether the document needs re-ingesting, without fetching `/content`. `null` for documents ingested before this field existed; it is not backfilled.", - "example": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", - "type": "string" - }, - "created_at": { - "description": "When the document was created (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", - "type": "string" - }, - "file": { - "description": "ID of the backing storage file (`fil_...`) when the document is file-backed. `null` for inline documents.", - "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "id": { - "description": "Context document ID (`cdo_...`).", - "example": "cdo_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" + "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" }, - "metadata": { - "description": "Arbitrary key-value metadata attached to the document. Shape varies by source type.", - "example": { - "key": "value" + "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" + }, + "type": "array" }, - "type": "object" - }, - "source": { - "description": "ID of the context source this document belongs to (`cso_...`).", - "example": "cso_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "team": { - "description": "ID of the team that owns this document (`tem_...`). `null` if owned by a user or agent.", - "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" + "principal": { + "description": "The identifier of the principal. A string ID for `\"user\"`, `\"team\"`, `\"org\"`, and `\"agent\"` types; one of `\"admin\"`, `\"member\"`, or `\"viewer\"` for `\"org_role\"`; omit entirely when `principal_type` is `\"everyone\"`.", + "example": "string", + "type": "string" + }, + "principal_type": { + "description": "The kind of principal receiving the grant. One of `\"user\"`, `\"team\"`, `\"org\"`, `\"org_role\"`, `\"agent\"`, or `\"everyone\"`.", + "example": "user", + "type": "string" + } }, - "title": { - "description": "Human-readable display title of the document. `null` if no title has been set.", - "example": "Example Title", - "type": "string" + "required": [ + "principal_type", + "actions" + ], + "type": "object" + }, + "type": "array" + }, + "grants": { + "description": "Replace mode: the complete new list of grants that replaces all existing entries. Send an empty array (`[]`) to clear all grants. Cannot be combined with `add` or `remove`.", + "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" }, - "total_lines": { - "description": "Total number of lines in the document's text content. `0` if the document has no content.", - "example": 1, - "type": "integer" + "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" + }, + "type": "array" + }, + "principal": { + "description": "The identifier of the principal. A string ID for `\"user\"`, `\"team\"`, `\"org\"`, and `\"agent\"` types; one of `\"admin\"`, `\"member\"`, or `\"viewer\"` for `\"org_role\"`; omit entirely when `principal_type` is `\"everyone\"`.", + "example": "string", + "type": "string" + }, + "principal_type": { + "description": "The kind of principal receiving the grant. One of `\"user\"`, `\"team\"`, `\"org\"`, `\"org_role\"`, `\"agent\"`, or `\"everyone\"`.", + "example": "user", + "type": "string" + } }, - "total_size": { - "description": "Total byte size of the document's text content. `0` if the document has no content.", - "example": 2048, - "type": "integer" + "required": [ + "principal_type", + "actions" + ], + "type": "object" + }, + "type": "array" + }, + "remove": { + "description": "Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`.", + "example": [ + { + "principal": "string", + "principal_type": "user" + } + ], + "items": { + "description": "Identifies a principal to be removed from an access-control list.", + "example": { + "principal": "string", + "principal_type": "user" }, - "updated_at": { - "description": "When the document was last modified (ISO 8601).", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", - "type": "string" + "properties": { + "principal": { + "description": "The identifier of the principal to remove. A string ID for `\"user\"`, `\"team\"`, `\"org\"`, and `\"agent\"` types; one of `\"admin\"`, `\"member\"`, or `\"viewer\"` for `\"org_role\"`. Omit when `principal_type` is `\"everyone\"`.", + "example": "string", + "type": "string" + }, + "principal_type": { + "description": "The kind of principal to remove. One of `\"user\"`, `\"team\"`, `\"org\"`, `\"org_role\"`, `\"agent\"`, or `\"everyone\"`.", + "example": "user", + "type": "string" + } }, - "user": { - "description": "ID of the user that owns this document (`usr_...`). `null` if owned by a team or agent.", - "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - } + "required": [ + "principal_type" + ], + "type": "object" }, - "required": [ - "id" - ], - "type": "object" - }, - "type": "array" - }, - "has_next": { - "description": "`true` if a subsequent page exists; `false` when this is the last page.", - "example": true, - "type": "boolean" - }, - "has_prev": { - "description": "`true` if a previous page exists; `false` when this is the first page.", - "example": true, - "type": "boolean" - }, - "page": { - "description": "The current page number.", - "example": 1, - "type": "integer" - }, - "page_size": { - "description": "Maximum number of documents returned per page.", - "example": 1, - "type": "integer" - }, - "total_entries": { - "description": "Total number of documents matching the applied filters across all pages.", - "example": 1, - "type": "integer" + "type": "array" + } }, - "total_pages": { - "description": "Total number of pages given the current `page_size`.", - "example": 1, - "type": "integer" - } + "type": "object" }, - "required": [ - "data", - "page", - "page_size", - "total_entries", - "total_pages", - "has_next", - "has_prev" - ], - "type": "object" + "agent": { + "description": "Agent ID (`agi_...`) to associate with this file. When provided, the file's organization is derived from the agent.", + "example": "string", + "type": "string" + }, + "content_type": { + "description": "MIME type of the file, e.g. `\"image/png\"` or `\"application/pdf\"`.", + "example": "application/json", + "type": "string" + }, + "data": { + "description": "Base64-encoded binary content of the file to upload.", + "example": "string", + "type": "string" + }, + "filename": { + "description": "Original filename including extension, e.g. `\"avatar.png\"`.", + "example": "string", + "type": "string" + }, + "org": { + "description": "Organization ID (`org_...`) to associate with this file. Optional; defaults to the viewer's organization when omitted.", + "example": "string", + "type": "string" + }, + "share": { + "description": "When `true`, marks the file publicly shareable and returns a stable, non-expiring `share_url` fetchable without authentication. Only image content types can be shared.", + "example": true, + "type": "boolean" + }, + "team": { + "description": "Team ID (`tem_...`) that owns this file. Takes precedence over `user` when both are provided.", + "example": "string", + "type": "string" + }, + "user": { + "description": "User ID (`usr_...`) that owns this file. Defaults to the authenticated user when neither `user` nor `team` is specified.", + "example": "string", + "type": "string" + } + }, + "required": [ + "data", + "content_type", + "filename" + ], + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "201": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/StorageFile" } } }, - "description": "Successful response" + "description": "The newly created file, including a signed download URL." }, "401": { "description": "Unauthorized" }, "403": { - "description": "App-scoped token required. Use a token scoped to the target app." + "description": "Forbidden - app scope required" + }, + "422": { + "description": "Validation failed or invalid base64" } }, - "summary": "List context documents", + "summary": "Upload a file", "x-auth": [ "publishable_key", "bearer" ] } }, - "/api/v1/knowledge_documents/{document}": { - "delete": { - "description": "Permanently deletes a context document and all of its associated chunk\nitems. This action is irreversible.\n\nThe backing storage file, if any, is not deleted — storage files can be\nshared across multiple documents and are cleaned up separately by the\nplatform's storage garbage collector. The caller must be authenticated\nand the request must be scoped to the app that owns the document.\n", - "operationId": "delete_api_v1_knowledge_documents__document", + "/api/v1/files/{file}": { + "patch": { + "description": "Updates mutable fields of an existing file. Only the fields you supply are\nchanged; omitted fields retain their current values. The file's stored content\nand `content_type` cannot be changed after creation.\n\nThis endpoint is the companion to `share: true` on file upload: the same\ncredential that granted public sharing can revoke it here with `share: false`\n(or grant it later with `share: true`; only image content types can be\nshared, and re-enabling sharing reactivates any previously issued share\nURLs). App scope is derived from the authenticated viewer, matching upload.\n\nA file that exists but is not visible to the current viewer returns `404`\nrather than `403` to avoid revealing the file's existence.\n", + "operationId": "patch_api_v1_files__file", "parameters": [ { - "description": "Document ID (`cdo_...`) to delete.", + "description": "File ID (`fil_...`) of the file to update.", "example": "string", "in": "path", - "name": "document", + "name": "file", "required": true, "schema": { "type": "string" } } ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "example": { + "filename": "string", + "provider_metadata": { + "key": "value" + }, + "share": true + }, + "properties": { + "filename": { + "description": "New name for the file, including extension, e.g. `\"report_v2.pdf\"`. Omit to leave the current filename unchanged.", + "example": "string", + "type": "string" + }, + "provider_metadata": { + "description": "Arbitrary key-value map of provider-specific metadata to store alongside the file. Replaces the entire existing `provider_metadata` map. Omit to leave it unchanged.", + "example": { + "key": "value" + }, + "type": "object" + }, + "share": { + "description": "Set `true` to mark the file publicly shareable via its stable `share_url` (image content types only), or `false` to revoke public sharing. Re-enabling sharing reactivates any previously issued share URLs for the file. Omit to leave sharing unchanged.", + "example": true, + "type": "boolean" + } + }, + "type": "object" + } + } + }, + "required": true + }, "responses": { - "204": { - "description": "Empty body. Returns HTTP 204 on success." + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/StorageFile" + } + } + }, + "description": "The updated file, including a signed download URL." }, "401": { "description": "Unauthorized" }, "403": { - "description": "App-scoped token required. Use a token scoped to the target app." + "description": "Forbidden - app scope required" }, "404": { - "description": "Knowledge document not found" + "description": "File not found" + }, + "422": { + "description": "Validation failed" } }, - "summary": "Delete a context document", + "summary": "Update a file", "x-auth": [ "publishable_key", "bearer" ] - }, + } + }, + "/api/v1/files/{file}/avatar": { "get": { - "description": "Returns a single context document identified by its ID. The response\nincludes document metadata such as title, size, and ownership fields,\nbut not the document's text content. To read the full or partial content,\nuse the content endpoint.\n\nThe caller must be authenticated and the request must be scoped to the\napp that owns the document.\n", - "operationId": "get_api_v1_knowledge_documents__document", + "description": "Returns the raw image bytes for an agent's profile picture identified by `file`.\nThis endpoint is designed for integration partners (such as Slack) that fetch\navatar URLs via plain GET requests without bearer token support. Authorization\nis performed via a short, stable capability `token` rather than an HTTP header.\n\nThe `token` is an HMAC-based capability tied to the file ID. It does not expire,\nbut it is invalidated when the agent's profile picture is replaced or the agent is\ndeleted — shared caches may continue serving the old image until the\n`Cache-Control` max-age of one hour elapses. The endpoint never redirects to\na signed storage URL; bytes are served inline so behavior is consistent across\nstorage backends.\n\nAll failure modes — invalid file ID, invalid token, file not currently referenced\nas an agent avatar — return a uniform `404` to avoid acting as an existence oracle.\n", + "operationId": "get_api_v1_files__file_avatar", "parameters": [ { - "description": "Document ID (`cdo_...`) to retrieve.", + "description": "File ID of the agent's profile picture (`fil_...`). Must be currently set as an agent's profile picture within the same app.", "example": "string", "in": "path", - "name": "document", + "name": "file", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "HMAC capability token authorizing access to this specific file. Obtained from the avatar URL minted when the profile picture was set.", + "example": "string", + "in": "query", + "name": "token", "required": true, "schema": { "type": "string" @@ -37100,197 +39753,88 @@ "responses": { "200": { "content": { - "application/json": { + "*/*": { "schema": { - "$ref": "#/components/schemas/ContextDocument" + "format": "binary", + "type": "string" } } }, - "description": "The requested context document's metadata." - }, - "401": { - "description": "Unauthorized" - }, - "403": { - "description": "App-scoped token required. Use a token scoped to the target app." + "description": "Raw image bytes of the agent avatar, served with the file's original content type." }, "404": { - "description": "Knowledge document not found" + "description": "Not found" } }, - "summary": "Retrieve a context document", - "x-auth": [ - "publishable_key", - "bearer" - ] - }, - "patch": { - "description": "Replaces one document's content while preserving its document ID. The update\nruns asynchronously through the document's source pipeline: bytes are\nextracted and chunked, the prior chunks are replaced atomically, and fresh\ndocument and chunk embeddings are queued.\n\nSupply exactly one of `file` or `content`. Omitted `title` and `metadata`\nretain their current values. The response is an ingestion that can be polled\nat `GET /api/v1/knowledge_ingestions/:id` until it reaches `succeeded` or\n`failed`. `succeeded` means the replacement content and full-text indexes are\ncommitted and the embedding refresh is durably queued; vector computation\ncontinues in the retryable embedding worker.\n", - "operationId": "patch_api_v1_knowledge_documents__document", - "parameters": [ - { - "description": "Document ID (`cdo_...`) to update.", - "example": "string", + "summary": "Fetch an agent avatar image" + } + }, + "/api/v1/files/{file}/org_logo": { + "get": { + "description": "Returns the raw image bytes for an organization's logo identified by `file`.\nThis endpoint backs the `org_logo.url` field of catalog payloads (such as\n`GET /api/v1/solutions`), which anonymous consumers — the public marketplace's\npage cache, OpenGraph scrapers — may hold far longer than a signed storage URL\nlives. Authorization is performed via a short, stable capability `token` rather\nthan an HTTP header, so the URL never expires.\n\nThe `token` is an HMAC-based capability tied to the file ID. It does not expire,\nbut it is invalidated when the org's logo is replaced or removed — shared caches\nmay continue serving the old image until the `Cache-Control` max-age of one hour\nelapses. The endpoint never redirects to a signed storage URL; bytes are served\ninline so behavior is consistent across storage backends.\n\nAll failure modes — invalid file ID, invalid token, file not currently referenced\nas an org logo — return a uniform `404` to avoid acting as an existence oracle.\n", + "operationId": "get_api_v1_files__file_org_logo", + "parameters": [ + { + "description": "File ID of the org's logo (`fil_...`). Must be currently set as an organization's logo within the same app.", + "example": "string", "in": "path", - "name": "document", + "name": "file", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "HMAC capability token authorizing access to this specific file. Obtained from the `org_logo.url` minted when the logo was serialized.", + "example": "string", + "in": "query", + "name": "token", "required": true, "schema": { "type": "string" } } ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "example": { - "content": { - "content_type": "application/json", - "data": "string", - "data_encoding": "string", - "filename": "string" - }, - "file": "string", - "metadata": { - "key": "value" - }, - "title": "Example Title" - }, - "properties": { - "content": { - "description": "Inline replacement bytes. Mutually exclusive with `file`.", - "example": { - "content_type": "application/json", - "data": "string", - "data_encoding": "string", - "filename": "string" - }, - "properties": { - "content_type": { - "description": "MIME type of the replacement content, such as `\"text/plain\"`.", - "example": "application/json", - "type": "string" - }, - "data": { - "description": "The replacement document bytes.", - "example": "string", - "type": "string" - }, - "data_encoding": { - "description": "Encoding of `data`: `\"raw\"` (default) or `\"base64\"`.", - "example": "string", - "type": "string" - }, - "filename": { - "description": "Original filename for the replacement content.", - "example": "string", - "type": "string" - } - }, - "required": [ - "data" - ], - "type": "object" - }, - "file": { - "description": "ID of an already-uploaded file (`fil_...`). Mutually exclusive with `content`.", - "example": "string", - "type": "string" - }, - "metadata": { - "description": "Replacement metadata map. Omit to retain the current metadata.", - "example": { - "key": "value" - }, - "type": "object" - }, - "title": { - "description": "Replacement display title. Omit to retain the current title.", - "example": "Example Title", - "type": "string" - } - }, - "type": "object" - } - } - }, - "required": true - }, "responses": { - "202": { + "200": { "content": { - "application/json": { + "*/*": { "schema": { - "$ref": "#/components/schemas/ContextIngestion" + "format": "binary", + "type": "string" } } }, - "description": "The ingestion performing the document update." - }, - "401": { - "description": "Unauthorized" - }, - "403": { - "description": "App-scoped token required. Use a token scoped to the target app.; Forbidden" + "description": "Raw image bytes of the org logo, served with the file's original content type." }, "404": { - "description": "Knowledge document not found" - }, - "422": { - "description": "Invalid parameters" - }, - "429": { - "description": "Too many requests" + "description": "Not found" } }, - "summary": "Update a context document", - "x-auth": [ - "publishable_key", - "bearer" - ] + "summary": "Fetch an org logo image" } }, - "/api/v1/knowledge_documents/{document}/content": { + "/api/v1/files/{file}/share": { "get": { - "description": "Returns the full text of a context document, or a slice of it when\n`offset`, `limit`, and `unit` are supplied. Both file-backed and inline\ndocuments are supported; the response shape is the same in either case.\n\nWhen slicing, set `unit` to `\"lines\"` (default) or `\"bytes\"`. A line-based\nslice uses a 1-indexed `offset`; a byte-based slice uses a 0-indexed\n`offset`. If you omit `offset`, the full document text is returned and the\nslice-specific response fields (`unit`, `offset`, `limit`, `start_line`,\n`end_line`, `start_byte`, `end_byte`) are absent.\n\nThe caller must be authenticated and the request must be scoped to an app\nthat owns the document.\n", - "operationId": "get_api_v1_knowledge_documents__document_content", + "description": "Returns the raw image bytes for a file that was explicitly shared for public\naccess, identified by `file`. This endpoint is designed for consumers that hold\na URL far longer than a signed storage URL lives — GitHub PR bodies (whose camo\nimage proxy re-fetches from the origin URL), wikis, and issue trackers — and\nfetch it via plain GET requests without bearer token support. Authorization is\nperformed via a short, stable capability `token` rather than an HTTP header.\n\nThe `token` is an HMAC-based capability tied to the file ID. It does not expire,\nbut it is invalidated when sharing is turned off for the file (`share: false` on\nthe file update endpoint) or the file is deleted — shared caches may continue\nserving the bytes until the `Cache-Control` max-age of one hour elapses. The\nendpoint never redirects to a signed storage URL; bytes are served inline so\nbehavior is consistent across storage backends. Only image content types are\nserved.\n\nAll failure modes — invalid file ID, invalid token, file not currently shared —\nreturn a uniform `404` to avoid acting as an existence oracle.\n", + "operationId": "get_api_v1_files__file_share", "parameters": [ { - "description": "Document ID (`cdo_...`) whose content to retrieve.", + "description": "File ID of the shared file (`fil_...`). The file must currently be marked as publicly shared.", "example": "string", "in": "path", - "name": "document", + "name": "file", "required": true, "schema": { "type": "string" } }, { - "description": "Starting position for a content slice. When `unit` is `\"lines\"`, this is a 1-indexed line number. When `unit` is `\"bytes\"`, this is a 0-indexed byte offset. Omit to return the full document.", - "example": 1, - "in": "query", - "name": "offset", - "required": false, - "schema": { - "type": "integer" - } - }, - { - "description": "Maximum number of units to return when slicing. Defaults to 200 when `unit` is `\"lines\"` and 8192 when `unit` is `\"bytes\"`.", - "example": 1, - "in": "query", - "name": "limit", - "required": false, - "schema": { - "type": "integer" - } - }, - { - "description": "Unit to use for `offset` and `limit`. One of `\"lines\"` (default) or `\"bytes\"`.", + "description": "HMAC capability token authorizing access to this specific file. Obtained from the `share_url` returned when the file was uploaded with `share: true`.", "example": "string", "in": "query", - "name": "unit", - "required": false, + "name": "token", + "required": true, "schema": { "type": "string" } @@ -37299,85 +39843,131 @@ "responses": { "200": { "content": { - "application/json": { + "*/*": { "schema": { - "$ref": "#/components/schemas/ContextDocumentContent" + "format": "binary", + "type": "string" } } }, - "description": "The document's content, optionally sliced by offset and limit." - }, - "401": { - "description": "Unauthorized" - }, - "403": { - "description": "App-scoped token required. Use a token scoped to the target app." + "description": "Raw image bytes of the shared file, served with the file's original content type." }, "404": { - "description": "Knowledge document not found" - }, - "422": { - "description": "Invalid parameters; Failed to load document content" + "description": "Not found" } }, - "summary": "Retrieve a context document's content", - "x-auth": [ - "publishable_key", - "bearer" - ] + "summary": "Fetch a publicly shared file" } }, - "/api/v1/knowledge_ingestions/{ingestion}": { - "get": { - "description": "Returns the status, error details, and metadata for a knowledge ingestion.\nUse the ingestion ID returned by an asynchronous knowledge source or document\noperation. Inaccessible and unknown ingestions both return 404.\n", - "operationId": "get_api_v1_knowledge_ingestions__ingestion", + "/api/v1/installation_sources/{source}": { + "delete": { + "description": "Detaches and permanently deletes a source from an installation. This action\ncannot be undone; the source and its associated content will no longer be\navailable to the installation's agent.\n\nThis endpoint requires an app-scoped token. You may identify the target\nindirectly by providing only the `source` ID — the installation is resolved\nautomatically from the source record. Providing `installation` explicitly\nis also accepted and may be more efficient.\n", + "operationId": "delete_api_v1_installation_sources__source", "parameters": [ { - "description": "Knowledge ingestion ID (`cig_...`) to retrieve.", + "description": "Source ID (`cso_...`) of the source to remove.", "example": "string", "in": "path", - "name": "ingestion", + "name": "source", "required": true, "schema": { "type": "string" } } ], + "responses": { + "204": { + "description": "No content" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden - app scope required" + }, + "404": { + "description": "Installation or source not found" + } + }, + "summary": "Remove a source from an installation", + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/invites/accept": { + "post": { + "description": "Accepts an invite on behalf of the authenticated user and adds them to the\nassociated team or thread. The invite `key` is passed in the request body\nrather than the URL so it never appears in access logs, `Referer` headers,\nor error-reporter URL captures.\n\nThis endpoint requires an authenticated end-user session. S2S secret-key\ntokens and unauthenticated requests are rejected with `401`. If the\nauthenticated user is already a member of the invite's target, the request\nreturns `409`. Both per-IP and per-user rate limits apply; exceeding either\nreturns `429`.\n", + "operationId": "post_api_v1_invites_accept", + "parameters": [], + "requestBody": { + "content": { + "application/json": { + "schema": { + "example": { + "key": "string" + }, + "properties": { + "key": { + "description": "Opaque invite key identifying the invite to accept. Obtained from an invite link or a previous invite creation response.", + "example": "string", + "type": "string" + } + }, + "required": [ + "key" + ], + "type": "object" + } + } + }, + "required": true + }, "responses": { "200": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ContextIngestion" + "$ref": "#/components/schemas/UserInvite" } } }, - "description": "The requested knowledge ingestion." + "description": "The accepted invite, including its ID, key, metadata, optional thread scope, creator, and creation timestamp." }, "401": { "description": "Unauthorized" }, "403": { - "description": "App-scoped token required. Use a token scoped to the target app." + "description": "Forbidden" }, "404": { - "description": "Knowledge ingestion not found" + "description": "Invite not found" + }, + "409": { + "description": "Conflict" + }, + "422": { + "description": "Validation failed" + }, + "429": { + "description": "Too many requests" } }, - "summary": "Retrieve a knowledge ingestion", + "summary": "Accept an invite", "x-auth": [ "publishable_key", "bearer" ] } }, - "/api/v1/knowledge_sources": { + "/api/v1/knowledge_documents": { "get": { - "description": "Returns a paginated list of knowledge sources visible to the authenticated caller.\nResults are ordered by creation time descending.\n\nUse the `type`, `installation`, `agent`, `org`, and `owner_scope` filters to narrow the\nresult set. Combine `owner_scope: \"system\"` with `org` to list org-level sources that\nhave no individual owner. Combine `owner_scope: \"individual\"` with `agent` to list\nsources owned by a specific agent.\n\nPagination is page-number based. The default page size is 25.\n", - "operationId": "get_api_v1_knowledge_sources", + "description": "Returns a paginated list of context documents visible to the authenticated\ncaller within the scoped app. Results are ordered by creation time\ndescending.\n\nUse `q` for a case-insensitive title prefix search. Use `source`,\n`installation`, or `agent` to narrow results to documents belonging to\nspecific sources, installations, or agents. Multiple values within each\nfilter are treated as OR conditions. Filters may be combined.\n\nThe response includes page-level metadata so you can navigate through\nlarge result sets without cursor tokens.\n", + "operationId": "get_api_v1_knowledge_documents", "parameters": [ { - "description": "Page number to retrieve. Defaults to 1.", + "description": "Page number to return. Defaults to 1.", "example": 1, "in": "query", "name": "page", @@ -37387,7 +39977,7 @@ } }, { - "description": "Number of knowledge sources to return per page. Defaults to 25.", + "description": "Number of documents per page. Defaults to 25.", "example": 1, "in": "query", "name": "page_size", @@ -37397,68 +39987,58 @@ } }, { - "description": "Filter sources whose type contains this string. Case-insensitive substring match.", + "description": "Case-insensitive prefix filter applied to the document title.", "example": "string", "in": "query", - "name": "search", + "name": "q", "required": false, "schema": { "type": "string" } }, { - "description": "Exact knowledge source type to filter by, e.g. `\"knowledge/documents\"`.", - "example": "string", + "description": "Return only documents belonging to these source IDs (`cso_...`). Multiple values are OR'd.", + "example": [ + "string" + ], "in": "query", - "name": "type", + "name": "source", "required": false, "schema": { - "type": "string" + "items": { + "type": "string" + }, + "type": "array" } }, { - "description": "Installation ID (`ins_...`). Returns only sources associated with this installation.", - "example": "string", + "description": "Return only documents belonging to these installation IDs. Multiple values are OR'd.", + "example": [ + "string" + ], "in": "query", "name": "installation", "required": false, "schema": { - "type": "string" + "items": { + "type": "string" + }, + "type": "array" } }, { - "description": "Agent ID (`agt_...`). Returns only sources owned by or associated with this agent.", - "example": "string", + "description": "Return only documents owned by these agent IDs. Multiple values are OR'd.", + "example": [ + "string" + ], "in": "query", "name": "agent", "required": false, "schema": { - "type": "string" - } - }, - { - "description": "Organization ID (`org_...`). Returns only sources belonging to this organization. Combine with `owner_scope: \"system\"` to retrieve org-level system sources.", - "example": "string", - "in": "query", - "name": "org", - "required": false, - "schema": { - "type": "string" - } - }, - { - "description": "Filter by ownership scope. One of `\"any\"` (default — returns all visible sources), `\"individual\"` (only sources owned by a user, team, or agent), or `\"system\"` (only sources with no individual owner, typically org-level).", - "example": "any", - "in": "query", - "name": "owner_scope", - "required": false, - "schema": { - "enum": [ - "any", - "individual", - "system" - ], - "type": "string" + "items": { + "type": "string" + }, + "type": "array" } } ], @@ -37467,27 +40047,23 @@ "content": { "application/json": { "schema": { - "description": "Paginated list of knowledge sources.", + "description": "Paginated list of context documents for the current page.", "example": { "data": [ { "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", - "context_installation": "cin_0aBcDeFgHiJkLmNoPqRsTu", + "content_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "created_at": "2024-01-01T00:00:00Z", - "id": "cso_0aBcDeFgHiJkLmNoPqRsTu", + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "id": "cdo_0aBcDeFgHiJkLmNoPqRsTu", "metadata": { "key": "value" }, - "org": "org_0aBcDeFgHiJkLmNoPqRsTu", - "parent_source": "cso_0aBcDeFgHiJkLmNoPqRsTu", - "payload": { - "key": "value" - }, - "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", - "state": "active", + "source": "cso_0aBcDeFgHiJkLmNoPqRsTu", "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", - "thread": "thr_0aBcDeFgHiJkLmNoPqRsTu", - "type": "gmail", + "title": "Example Title", + "total_lines": 1, + "total_size": 2048, "updated_at": "2024-01-01T00:00:00Z", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" } @@ -37501,172 +40077,150 @@ }, "properties": { "data": { - "description": "Array of knowledge source objects for the current page.", + "description": "Array of context document objects for the current page.", "example": [ { "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", - "context_installation": "cin_0aBcDeFgHiJkLmNoPqRsTu", + "content_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "created_at": "2024-01-01T00:00:00Z", - "id": "cso_0aBcDeFgHiJkLmNoPqRsTu", + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "id": "cdo_0aBcDeFgHiJkLmNoPqRsTu", "metadata": { "key": "value" }, - "org": "org_0aBcDeFgHiJkLmNoPqRsTu", - "parent_source": "cso_0aBcDeFgHiJkLmNoPqRsTu", - "payload": { - "key": "value" - }, - "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", - "state": "active", + "source": "cso_0aBcDeFgHiJkLmNoPqRsTu", "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", - "thread": "thr_0aBcDeFgHiJkLmNoPqRsTu", - "type": "gmail", + "title": "Example Title", + "total_lines": 1, + "total_size": 2048, "updated_at": "2024-01-01T00:00:00Z", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" } ], "items": { - "description": "A knowledge source that ingests content into the knowledge base. Sources connect to external systems (e.g. Gmail, GitHub) and continuously or on-demand index items for search.", + "description": "A context document stored within a context source. Carries metadata and size information only; retrieve the full text content via the `/content` endpoint.\n", "example": { "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", - "context_installation": "cin_0aBcDeFgHiJkLmNoPqRsTu", + "content_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "created_at": "2024-01-01T00:00:00Z", - "id": "cso_0aBcDeFgHiJkLmNoPqRsTu", + "file": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "id": "cdo_0aBcDeFgHiJkLmNoPqRsTu", "metadata": { "key": "value" }, - "org": "org_0aBcDeFgHiJkLmNoPqRsTu", - "parent_source": "cso_0aBcDeFgHiJkLmNoPqRsTu", - "payload": { - "key": "value" - }, - "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", - "state": "active", + "source": "cso_0aBcDeFgHiJkLmNoPqRsTu", "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", - "thread": "thr_0aBcDeFgHiJkLmNoPqRsTu", - "type": "gmail", + "title": "Example Title", + "total_lines": 1, + "total_size": 2048, "updated_at": "2024-01-01T00:00:00Z", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" }, "properties": { "agent": { - "description": "ID of the agent that owns this source (`agt_...`). `null` if owned by a human user or team.", + "description": "ID of the agent that owns this document (`agi_...`). `null` if owned by a user or team.", "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", "type": "string" }, - "context_installation": { - "description": "ID of the context installation that provisioned this source (`cin_...`). `null` when the source was created directly rather than through an installation.", - "example": "cin_0aBcDeFgHiJkLmNoPqRsTu", + "content_hash": { + "description": "Lowercase-hex sha256 of the document's full text, covering content only — not `title` or `metadata`. Compare it against a hash of your local copy to decide whether the document needs re-ingesting, without fetching `/content`. `null` for documents ingested before this field existed; it is not backfilled.", + "example": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "type": "string" }, "created_at": { - "description": "When this knowledge source was created (ISO 8601).", + "description": "When the document was created (ISO 8601).", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, + "file": { + "description": "ID of the backing storage file (`fil_...`) when the document is file-backed. `null` for inline documents.", + "example": "fil_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, "id": { - "description": "Knowledge source ID (`cso_...`).", - "example": "cso_0aBcDeFgHiJkLmNoPqRsTu", + "description": "Context document ID (`cdo_...`).", + "example": "cdo_0aBcDeFgHiJkLmNoPqRsTu", "type": "string" }, "metadata": { - "description": "Arbitrary key-value metadata attached to this source. Useful for storing caller-defined labels or references.", + "description": "Arbitrary key-value metadata attached to the document. Shape varies by source type.", "example": { "key": "value" }, "type": "object" }, - "org": { - "description": "ID of the organization this source belongs to (`org_...`). `null` if not scoped to an org.", - "example": "org_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "parent_source": { - "description": "ID of the parent knowledge source (`cso_...`) when this source was derived from another. `null` for top-level sources.", + "source": { + "description": "ID of the context source this document belongs to (`cso_...`).", "example": "cso_0aBcDeFgHiJkLmNoPqRsTu", "type": "string" }, - "payload": { - "description": "Type-specific configuration object. The keys depend on the source `type`; see the create endpoint for the expected shape per type.", - "example": { - "key": "value" - }, - "type": "object" - }, - "sandbox": { - "description": "ID of the developer sandbox this source is scoped to (`sbx_...`). `null` outside sandbox contexts.", - "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "state": { - "description": "Current lifecycle state of the source. One of `\"active\"` (ingestion running normally) or `\"paused\"` (ingestion suspended).", - "example": "active", - "type": "string" - }, "team": { - "description": "ID of the team that owns this source (`tea_...`). `null` if owned by a user, agent, or org.", + "description": "ID of the team that owns this document (`tem_...`). `null` if owned by a user or agent.", "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", "type": "string" }, - "thread": { - "description": "ID of the chat thread this source is associated with (`thr_...`). `null` when not thread-scoped.", - "example": "thr_0aBcDeFgHiJkLmNoPqRsTu", + "title": { + "description": "Human-readable display title of the document. `null` if no title has been set.", + "example": "Example Title", "type": "string" }, - "type": { - "description": "Source type identifier (e.g. `\"gmail\"`, `\"github_activity\"`). Determines the shape of `payload` and the ingestion behavior.", - "example": "gmail", - "type": "string" + "total_lines": { + "description": "Total number of lines in the document's text content. `0` if the document has no content.", + "example": 1, + "type": "integer" + }, + "total_size": { + "description": "Total byte size of the document's text content. `0` if the document has no content.", + "example": 2048, + "type": "integer" }, "updated_at": { - "description": "When this knowledge source was last modified (ISO 8601).", + "description": "When the document 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 source (`usr_...`). `null` if owned by a team, agent, or org.", + "description": "ID of the user that owns this document (`usr_...`). `null` if owned by a team or agent.", "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", "type": "string" } }, "required": [ - "id", - "type", - "state" + "id" ], "type": "object" }, "type": "array" }, "has_next": { - "description": "`true` if a subsequent page exists, `false` if this is the last page.", + "description": "`true` if a subsequent page exists; `false` when this is the last page.", "example": true, "type": "boolean" }, "has_prev": { - "description": "`true` if a previous page exists, `false` if this is the first page.", + "description": "`true` if a previous page exists; `false` when this is the first page.", "example": true, "type": "boolean" }, "page": { - "description": "Current page number.", + "description": "The current page number.", "example": 1, "type": "integer" }, "page_size": { - "description": "Number of results returned per page.", + "description": "Maximum number of documents returned per page.", "example": 1, "type": "integer" }, "total_entries": { - "description": "Total number of knowledge sources matching the query across all pages.", + "description": "Total number of documents matching the applied filters across all pages.", "example": 1, "type": "integer" }, "total_pages": { - "description": "Total number of pages available.", + "description": "Total number of pages given the current `page_size`.", "example": 1, "type": "integer" } @@ -37693,165 +40247,23 @@ "description": "App-scoped token required. Use a token scoped to the target app." } }, - "summary": "List knowledge sources", - "x-auth": [ - "publishable_key", - "bearer" - ] - }, - "post": { - "description": "Creates a new knowledge source of the requested type and returns the created object.\n\nOnly types listed by `GET /api/v1/knowledge_sources/kinds` may be created through this\nendpoint. Other source types — such as `webhook/inbound`, `connectors/*/emails`, and\n`thread/messages` — are provisioned automatically by server-driven flows (webhook\nauto-provisioning, installation activation, connector lifecycle events) and cannot be\ncreated directly via the API.\n\nExactly one of `team`, `user`, `agent`, or `org` must identify the owner of the new\nsource. Omit `org` when an individual owner (`team`, `user`, or `agent`) is supplied;\ninclude `org` alone for org-level system-owned sources.\n", - "operationId": "post_api_v1_knowledge_sources", - "parameters": [], - "requestBody": { - "content": { - "application/json": { - "schema": { - "example": { - "agent": "string", - "metadata": { - "key": "value" - }, - "org": "string", - "parent_source": "string", - "payload": {}, - "state": "string", - "team": "string", - "thread": "string", - "type": "string", - "user": "string" - }, - "properties": { - "agent": { - "description": "Agent ID (`agt_...`) that owns this source. Mutually exclusive with `team` and `user`.", - "example": "string", - "type": "string" - }, - "metadata": { - "description": "Arbitrary key-value metadata to attach to the source. Returned as-is on reads.", - "example": { - "key": "value" - }, - "type": "object" - }, - "org": { - "description": "Organization ID (`org_...`). Required for system-owned sources that have no individual owner (`team`, `user`, or `agent`).", - "example": "string", - "type": "string" - }, - "parent_source": { - "description": "Parent knowledge source ID (`ksrc_...`). Use to create a child source.", - "example": "string", - "type": "string" - }, - "payload": { - "description": "Type-specific configuration for the source. Shape depends on `type`.", - "example": {}, - "type": "object" - }, - "state": { - "description": "Initial state of the source. One of `\"active\"` (default) or `\"paused\"`. Paused sources do not trigger ingestion automatically.", - "example": "string", - "type": "string" - }, - "team": { - "description": "Team ID (`team_...`) that owns this source. Mutually exclusive with `user` and `agent`.", - "example": "string", - "type": "string" - }, - "thread": { - "description": "Thread ID (`thr_...`) to associate this source with, if applicable.", - "example": "string", - "type": "string" - }, - "type": { - "description": "Knowledge source type. Must be one of the values returned by `GET /api/v1/knowledge_sources/kinds`.", - "example": "string", - "type": "string" - }, - "user": { - "description": "User ID (`usr_...`) that owns this source. Mutually exclusive with `team` and `agent`.", - "example": "string", - "type": "string" - } - }, - "required": [ - "type" - ], - "type": "object" - } - } - }, - "required": true - }, - "responses": { - "201": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/KnowledgeSource" - } - } - }, - "description": "The newly created knowledge source." - }, - "401": { - "description": "Unauthorized" - }, - "403": { - "description": "App-scoped token required. Use a token scoped to the target app.; Forbidden" - }, - "422": { - "description": "Invalid parameters; Validation failed" - } - }, - "summary": "Create a knowledge source", - "x-auth": [ - "publishable_key", - "bearer" - ] - } - }, - "/api/v1/knowledge_sources/kinds": { - "get": { - "description": "Returns the fixed set of knowledge source types that can be created directly via\n`POST /api/v1/knowledge_sources`. Use this endpoint to discover valid values for the\n`type` param before calling the create endpoint.\n\nSource kinds populated by server-driven flows — such as `webhook/inbound`,\n`connectors/*/emails`, and `thread/messages` — are intentionally excluded from this\nlist, as they cannot be created through the API.\n", - "operationId": "get_api_v1_knowledge_sources_kinds", - "parameters": [], - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/KnowledgeSourceKindListResponse" - } - } - }, - "description": "List of knowledge source kinds available for creation via the API." - }, - "401": { - "description": "Unauthorized" - }, - "403": { - "description": "App-scoped token required. Use a token scoped to the target app." - } - }, - "summary": "List creatable knowledge source kinds", + "summary": "List context documents", "x-auth": [ "publishable_key", "bearer" ] } }, - "/api/v1/knowledge_sources/{source}": { + "/api/v1/knowledge_documents/{document}": { "delete": { - "description": "Permanently deletes the knowledge source identified by `source`. This action is\nirreversible — all documents, embeddings, and ingestion history associated with the\nsource are removed.\n\nThe authenticated caller must own the source or have sufficient permissions within its\nparent organization. Returns `204 No Content` on success.\n", - "operationId": "delete_api_v1_knowledge_sources__source", + "description": "Permanently deletes a context document and all of its associated chunk\nitems. This action is irreversible.\n\nThe backing storage file, if any, is not deleted — storage files can be\nshared across multiple documents and are cleaned up separately by the\nplatform's storage garbage collector. The caller must be authenticated\nand the request must be scoped to the app that owns the document.\n", + "operationId": "delete_api_v1_knowledge_documents__document", "parameters": [ { - "description": "Knowledge source ID (`ksrc_...`) to delete.", + "description": "Document ID (`cdo_...`) to delete.", "example": "string", "in": "path", - "name": "source", + "name": "document", "required": true, "schema": { "type": "string" @@ -37860,33 +40272,33 @@ ], "responses": { "204": { - "description": "Empty response. The source has been permanently deleted." + "description": "Empty body. Returns HTTP 204 on success." }, "401": { "description": "Unauthorized" }, "403": { - "description": "App-scoped token required. Use a token scoped to the target app.; Forbidden" + "description": "App-scoped token required. Use a token scoped to the target app." }, "404": { - "description": "Knowledge source not found" + "description": "Knowledge document not found" } }, - "summary": "Delete a knowledge source", + "summary": "Delete a context document", "x-auth": [ "publishable_key", "bearer" ] }, "get": { - "description": "Returns the knowledge source identified by `source`. The authenticated caller must have\naccess to the source's parent organization or be the individual owner of the source.\n\nUse the list endpoint to retrieve many sources at once or to discover sources by type\nor owner.\n", - "operationId": "get_api_v1_knowledge_sources__source", + "description": "Returns a single context document identified by its ID. The response\nincludes document metadata such as title, size, and ownership fields,\nbut not the document's text content. To read the full or partial content,\nuse the content endpoint.\n\nThe caller must be authenticated and the request must be scoped to the\napp that owns the document.\n", + "operationId": "get_api_v1_knowledge_documents__document", "parameters": [ { - "description": "Knowledge source ID (`ksrc_...`) to retrieve.", + "description": "Document ID (`cdo_...`) to retrieve.", "example": "string", "in": "path", - "name": "source", + "name": "document", "required": true, "schema": { "type": "string" @@ -37898,11 +40310,11 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/KnowledgeSource" + "$ref": "#/components/schemas/ContextDocument" } } }, - "description": "The requested knowledge source." + "description": "The requested context document's metadata." }, "401": { "description": "Unauthorized" @@ -37911,107 +40323,24 @@ "description": "App-scoped token required. Use a token scoped to the target app." }, "404": { - "description": "Knowledge source not found" + "description": "Knowledge document not found" } }, - "summary": "Retrieve a knowledge source", + "summary": "Retrieve a context document", "x-auth": [ "publishable_key", "bearer" ] }, "patch": { - "description": "Updates the mutable fields of an existing knowledge source and returns the updated\nobject. Only fields provided in the request body are changed; omitted fields retain\ntheir current values.\n\nYou can update the type-specific `payload`, the `metadata` map, and the `state`. To\npause a source and prevent automatic ingestion, set `state` to `\"paused\"`. To resume,\nset it back to `\"active\"`.\n", - "operationId": "patch_api_v1_knowledge_sources__source", - "parameters": [ - { - "description": "Knowledge source ID (`ksrc_...`) to update.", - "example": "string", - "in": "path", - "name": "source", - "required": true, - "schema": { - "type": "string" - } - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "example": { - "metadata": { - "key": "value" - }, - "payload": {}, - "state": "string" - }, - "properties": { - "metadata": { - "description": "Arbitrary key-value metadata to attach to the source. Replaces the entire existing `metadata` map when provided.", - "example": { - "key": "value" - }, - "type": "object" - }, - "payload": { - "description": "Type-specific configuration to replace on the source. Shape depends on the source `type`. Replaces the entire existing `payload` when provided.", - "example": {}, - "type": "object" - }, - "state": { - "description": "Desired state of the source. One of `\"active\"` or `\"paused\"`. Paused sources do not trigger ingestion automatically.", - "example": "string", - "type": "string" - } - }, - "type": "object" - } - } - }, - "required": true - }, - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/KnowledgeSource" - } - } - }, - "description": "The updated knowledge source." - }, - "401": { - "description": "Unauthorized" - }, - "403": { - "description": "App-scoped token required. Use a token scoped to the target app.; Forbidden" - }, - "404": { - "description": "Knowledge source not found" - }, - "422": { - "description": "Validation failed" - } - }, - "summary": "Update a knowledge source", - "x-auth": [ - "publishable_key", - "bearer" - ] - } - }, - "/api/v1/knowledge_sources/{source}/ingest": { - "post": { - "description": "Starts an ingestion run on the specified knowledge source and returns the ingestion\nobject. Exactly one of two modes must be chosen per request:\n\n**Push mode** (`file` or `content`) — available for `knowledge/documents` sources only.\nSupply the document bytes either as a reference to an already-uploaded file (`file`) or\nas an inline blob (`content`). The runner stores the bytes and indexes the resulting\ndocument. `title` and `metadata` are persisted on the document in push mode.\n\n**Pull mode** (`pull: true`) — re-triggers ingestion using the source's own configured\ndata. Use this to re-scrape a `scrape/site`, re-fetch a `web/link`, or re-process a\n`file/document`. Not valid for `knowledge/documents` (which has no upstream — push new\nbytes instead) or for source kinds populated by server-driven flows. `title` and\n`metadata` are ignored in pull mode.\n\nIf an ingestion is already active for the source, the existing ingestion is returned\nrather than creating a duplicate.\n", - "operationId": "post_api_v1_knowledge_sources__source_ingest", + "description": "Replaces one document's content while preserving its document ID. The update\nruns asynchronously through the document's source pipeline: bytes are\nextracted and chunked, the prior chunks are replaced atomically, and fresh\ndocument and chunk embeddings are queued.\n\nSupply exactly one of `file` or `content`. Omitted `title` and `metadata`\nretain their current values. The response is an ingestion that can be polled\nat `GET /api/v1/knowledge_ingestions/:id` until it reaches `succeeded` or\n`failed`. `succeeded` means the replacement content and full-text indexes are\ncommitted and the embedding refresh is durably queued; vector computation\ncontinues in the retryable embedding worker.\n", + "operationId": "patch_api_v1_knowledge_documents__document", "parameters": [ { - "description": "Knowledge source ID (`ksrc_...`) to ingest.", + "description": "Document ID (`cdo_...`) to update.", "example": "string", "in": "path", - "name": "source", + "name": "document", "required": true, "schema": { "type": "string" @@ -38029,17 +40358,15 @@ "data_encoding": "string", "filename": "string" }, - "dedupe": true, "file": "string", "metadata": { "key": "value" }, - "pull": true, "title": "Example Title" }, "properties": { "content": { - "description": "Inline document bytes to push to the source. Mutually exclusive with `file` and `pull`.", + "description": "Inline replacement bytes. Mutually exclusive with `file`.", "example": { "content_type": "application/json", "data": "string", @@ -38048,22 +40375,22 @@ }, "properties": { "content_type": { - "description": "MIME type of the content, e.g. `\"application/pdf\"` or `\"text/plain\"`.", + "description": "MIME type of the replacement content, such as `\"text/plain\"`.", "example": "application/json", "type": "string" }, "data": { - "description": "The raw document bytes. When `data_encoding` is `\"base64\"`, provide the base64-encoded representation of the binary content.", + "description": "The replacement document bytes.", "example": "string", "type": "string" }, "data_encoding": { - "description": "Encoding format of `data`. One of `\"raw\"` (default, plain text) or `\"base64\"` (binary content such as images or PDFs, decoded server-side before storage).", + "description": "Encoding of `data`: `\"raw\"` (default) or `\"base64\"`.", "example": "string", "type": "string" }, "filename": { - "description": "Original filename for the document, e.g. `\"report.pdf\"`.", + "description": "Original filename for the replacement content.", "example": "string", "type": "string" } @@ -38073,30 +40400,20 @@ ], "type": "object" }, - "dedupe": { - "description": "When `true`, reuse the source's existing document if the pushed content is byte-identical to it, instead of creating a duplicate. The reused document keeps its chunks and embeddings, and `title`/`metadata` from this request are still applied to it. Content that differs in any way always creates a new document. Defaults to `false`, which creates a new document on every push. Push mode only — not valid with `pull: true`. Check `metadata.document_reused` on the returned ingestion to see whether a document was actually reused.", - "example": true, - "type": "boolean" - }, "file": { - "description": "ID of an already-uploaded file (`fil_...`). The runner reads filename and content type from the stored file. Upload the file via `POST /v1/files` first. Mutually exclusive with `content` and `pull`.", + "description": "ID of an already-uploaded file (`fil_...`). Mutually exclusive with `content`.", "example": "string", "type": "string" }, "metadata": { - "description": "Arbitrary key-value metadata to attach to the ingested document. Applied in push mode only; ignored when `pull: true`.", + "description": "Replacement metadata map. Omit to retain the current metadata.", "example": { "key": "value" }, "type": "object" }, - "pull": { - "description": "When `true`, re-triggers ingestion using the source's own configured data. Re-scrapes a `scrape/site`, re-fetches a `web/link`, or re-processes a `file/document`. Mutually exclusive with `file` and `content`. Not valid for `knowledge/documents` sources.", - "example": true, - "type": "boolean" - }, "title": { - "description": "Display title for the ingested document. Applied in push mode only; ignored when `pull: true`.", + "description": "Replacement display title. Omit to retain the current title.", "example": "Example Title", "type": "string" } @@ -38108,7 +40425,7 @@ "required": true }, "responses": { - "201": { + "202": { "content": { "application/json": { "schema": { @@ -38116,7 +40433,7 @@ } } }, - "description": "The created ingestion, or an existing active ingestion if one is already running." + "description": "The ingestion performing the document update." }, "401": { "description": "Unauthorized" @@ -38125,7 +40442,7 @@ "description": "App-scoped token required. Use a token scoped to the target app.; Forbidden" }, "404": { - "description": "Knowledge source not found" + "description": "Knowledge document not found" }, "422": { "description": "Invalid parameters" @@ -38134,63 +40451,53 @@ "description": "Too many requests" } }, - "summary": "Trigger ingestion on a knowledge source", + "summary": "Update a context document", "x-auth": [ "publishable_key", "bearer" ] } }, - "/api/v1/kv": { + "/api/v1/knowledge_documents/{document}/content": { "get": { - "description": "Returns key-value storage entries in one of two modes depending on the caller's\nauth scope.\n\n**User-JWT callers** receive a flat list of all their own entries with no\npagination fields. The `page`, `page_size`, `user`, `user_search`, and `key`\nparams are ignored.\n\n**Developer and server-to-server callers** receive a page-based paginated\nresponse across all users within the caller's app. Use `user` to scope results\nto a single user, `user_search` to do a substring match on email or full name,\nand `key` to filter entries whose key starts with the given prefix. Results are\nordered by creation time descending.\n", - "operationId": "get_api_v1_kv", + "description": "Returns the full text of a context document, or a slice of it when\n`offset`, `limit`, and `unit` are supplied. Both file-backed and inline\ndocuments are supported; the response shape is the same in either case.\n\nWhen slicing, set `unit` to `\"lines\"` (default) or `\"bytes\"`. A line-based\nslice uses a 1-indexed `offset`; a byte-based slice uses a 0-indexed\n`offset`. If you omit `offset`, the full document text is returned and the\nslice-specific response fields (`unit`, `offset`, `limit`, `start_line`,\n`end_line`, `start_byte`, `end_byte`) are absent.\n\nThe caller must be authenticated and the request must be scoped to an app\nthat owns the document.\n", + "operationId": "get_api_v1_knowledge_documents__document_content", "parameters": [ { - "description": "Page number to retrieve. Applies to developer and server-to-server callers only. Defaults to 1.", - "example": 1, - "in": "query", - "name": "page", - "required": false, + "description": "Document ID (`cdo_...`) whose content to retrieve.", + "example": "string", + "in": "path", + "name": "document", + "required": true, "schema": { - "type": "integer" + "type": "string" } }, { - "description": "Number of entries per page. Applies to developer and server-to-server callers only. Defaults to 25; maximum is 100.", + "description": "Starting position for a content slice. When `unit` is `\"lines\"`, this is a 1-indexed line number. When `unit` is `\"bytes\"`, this is a 0-indexed byte offset. Omit to return the full document.", "example": 1, "in": "query", - "name": "page_size", + "name": "offset", "required": false, "schema": { "type": "integer" } }, { - "description": "Filter results to entries belonging to this user ID. Applies to developer and server-to-server callers only.", - "example": "string", - "in": "query", - "name": "user", - "required": false, - "schema": { - "type": "string" - } - }, - { - "description": "Substring match against user email address and full name. Applies to developer and server-to-server callers only.", - "example": "string", + "description": "Maximum number of units to return when slicing. Defaults to 200 when `unit` is `\"lines\"` and 8192 when `unit` is `\"bytes\"`.", + "example": 1, "in": "query", - "name": "user_search", + "name": "limit", "required": false, "schema": { - "type": "string" + "type": "integer" } }, { - "description": "Prefix filter on the storage key. Returns only entries whose key starts with this string. Applies to developer and server-to-server callers only.", + "description": "Unit to use for `offset` and `limit`. One of `\"lines\"` (default) or `\"bytes\"`.", "example": "string", "in": "query", - "name": "key", + "name": "unit", "required": false, "schema": { "type": "string" @@ -38202,112 +40509,42 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/KeyValueStorageEntryPage" + "$ref": "#/components/schemas/ContextDocumentContent" } } }, - "description": "Key-value storage entries for the current page, with pagination metadata for developer and server-to-server callers." - }, - "400": { - "description": "Bad request" + "description": "The document's content, optionally sliced by offset and limit." }, "401": { "description": "Unauthorized" }, "403": { "description": "App-scoped token required. Use a token scoped to the target app." - } - }, - "summary": "List key-value storage entries", - "x-auth": [ - "publishable_key", - "bearer" - ] - }, - "post": { - "description": "Creates a new key-value storage entry for the target user under the given key.\nThe key must not already exist for this user; use the upsert endpoint to create\nor overwrite in a single call.\n\nEnd-user (user-JWT) callers always write to their own storage. Developer and\nserver-to-server callers must supply a `user` param identifying the target user\nwithin their app's scope. Attempting to write for a user in a different app\nreturns 404.\n", - "operationId": "post_api_v1_kv", - "parameters": [], - "requestBody": { - "content": { - "application/json": { - "schema": { - "example": { - "key": "string", - "user": "string", - "value": "string" - }, - "properties": { - "key": { - "description": "Storage key for the entry. Must be a non-empty string unique to this user.", - "example": "string", - "type": "string" - }, - "user": { - "description": "Target user ID. Required when calling as a developer or with a server-to-server key; ignored for end-user callers.", - "example": "string", - "type": "string" - }, - "value": { - "description": "Value to store under `key`. Must be a non-empty string.", - "example": "string", - "type": "string" - } - }, - "required": [ - "key", - "value" - ], - "type": "object" - } - } - }, - "required": true - }, - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/KeyValueStorageEntry" - } - } - }, - "description": "The newly created key-value storage entry." - }, - "400": { - "description": "Bad request" - }, - "401": { - "description": "Unauthorized" - }, - "403": { - "description": "Forbidden; App-scoped token required. Use a token scoped to the target app." }, "404": { - "description": "User not found" + "description": "Knowledge document not found" }, "422": { - "description": "Invalid parameters" + "description": "Invalid parameters; Failed to load document content" } }, - "summary": "Create a key-value storage entry", + "summary": "Retrieve a context document's content", "x-auth": [ "publishable_key", "bearer" ] } }, - "/api/v1/kv/{key}": { - "delete": { - "description": "Permanently deletes the key-value storage entry identified by `key` for the\ntarget user. Returns 204 No Content on success and 404 if the entry does not\nexist.\n\nEnd-user (user-JWT) callers can only delete entries they own. Developer and\nserver-to-server callers must supply a `user` param identifying the target user\nwithin their app's scope.\n", - "operationId": "delete_api_v1_kv__key", + "/api/v1/knowledge_ingestions/{ingestion}": { + "get": { + "description": "Returns the status, error details, and metadata for a knowledge ingestion.\nUse the ingestion ID returned by an asynchronous knowledge source or document\noperation. Inaccessible and unknown ingestions both return 404.\n", + "operationId": "get_api_v1_knowledge_ingestions__ingestion", "parameters": [ { - "description": "Storage key of the entry to delete. Must be a non-empty string.", + "description": "Knowledge ingestion ID (`cig_...`) to retrieve.", "example": "string", "in": "path", - "name": "key", + "name": "ingestion", "required": true, "schema": { "type": "string" @@ -38315,322 +40552,120 @@ } ], "responses": { - "204": { - "description": "Empty response body. HTTP 204 No Content on success." - }, - "400": { - "description": "Bad request" + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContextIngestion" + } + } + }, + "description": "The requested knowledge ingestion." }, "401": { "description": "Unauthorized" }, "403": { - "description": "Forbidden; App-scoped token required. Use a token scoped to the target app." + "description": "App-scoped token required. Use a token scoped to the target app." }, "404": { - "description": "Entry not found; User not found" + "description": "Knowledge ingestion not found" } }, - "summary": "Delete a key-value storage entry", + "summary": "Retrieve a knowledge ingestion", "x-auth": [ "publishable_key", "bearer" ] - }, + } + }, + "/api/v1/knowledge_sources": { "get": { - "description": "Returns the key-value storage entry identified by `key` for the target user.\nReturns 404 if no entry exists for that key.\n\nEnd-user (user-JWT) callers retrieve entries from their own storage. Developer\nand server-to-server callers must supply a `user` param identifying the target\nuser within their app's scope.\n", - "operationId": "get_api_v1_kv__key", + "description": "Returns a paginated list of knowledge sources visible to the authenticated caller.\nResults are ordered by creation time descending.\n\nUse the `type`, `installation`, `agent`, `org`, and `owner_scope` filters to narrow the\nresult set. Combine `owner_scope: \"system\"` with `org` to list org-level sources that\nhave no individual owner. Combine `owner_scope: \"individual\"` with `agent` to list\nsources owned by a specific agent.\n\nPagination is page-number based. The default page size is 25.\n", + "operationId": "get_api_v1_knowledge_sources", "parameters": [ { - "description": "Storage key of the entry to retrieve. Must be a non-empty string.", - "example": "string", - "in": "path", - "name": "key", - "required": true, + "description": "Page number to retrieve. Defaults to 1.", + "example": 1, + "in": "query", + "name": "page", + "required": false, "schema": { - "type": "string" + "type": "integer" } }, { - "description": "Target user ID. Required when calling as a developer or with a server-to-server key; ignored for end-user callers.", - "example": "string", + "description": "Number of knowledge sources to return per page. Defaults to 25.", + "example": 1, "in": "query", - "name": "user", + "name": "page_size", "required": false, "schema": { - "type": "string" + "type": "integer" } - } - ], - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/KeyValueStorageEntry" - } - } - }, - "description": "The key-value storage entry for the given key." }, - "400": { - "description": "Bad request" - }, - "401": { - "description": "Unauthorized" - }, - "403": { - "description": "Forbidden; App-scoped token required. Use a token scoped to the target app." - }, - "404": { - "description": "Entry not found; User not found" - } - }, - "summary": "Retrieve a key-value storage entry", - "x-auth": [ - "publishable_key", - "bearer" - ] - }, - "put": { - "description": "Creates a new key-value storage entry for the given `key`, or overwrites the\nvalue if an entry already exists. This is the idempotent alternative to the\ncreate endpoint: safe to call regardless of whether the key already exists.\n\nEnd-user (user-JWT) callers always write to their own storage. Developer and\nserver-to-server callers must supply a `user` param identifying the target user\nwithin their app's scope. Attempting to write for a user in a different app\nreturns 404.\n", - "operationId": "put_api_v1_kv__key", - "parameters": [ { - "description": "Storage key to create or overwrite. Must be a non-empty string.", + "description": "Filter sources whose type contains this string. Case-insensitive substring match.", "example": "string", - "in": "path", - "name": "key", - "required": true, + "in": "query", + "name": "search", + "required": false, "schema": { "type": "string" } - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "example": { - "user": "string", - "value": "string" - }, - "properties": { - "user": { - "description": "Target user ID. Required when calling as a developer or with a server-to-server key; ignored for end-user callers.", - "example": "string", - "type": "string" - }, - "value": { - "description": "New value to store under `key`. Must be a non-empty string. Replaces any existing value.", - "example": "string", - "type": "string" - } - }, - "required": [ - "value" - ], - "type": "object" - } - } - }, - "required": true - }, - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/KeyValueStorageEntry" - } - } - }, - "description": "The created or updated key-value storage entry." - }, - "400": { - "description": "Bad request" - }, - "401": { - "description": "Unauthorized" - }, - "403": { - "description": "Forbidden; App-scoped token required. Use a token scoped to the target app." - }, - "404": { - "description": "User not found" - }, - "422": { - "description": "Invalid parameters" - } - }, - "summary": "Create or update a key-value storage entry", - "x-auth": [ - "publishable_key", - "bearer" - ], - "x-sdk-name": "upsert" - } - }, - "/api/v1/notification_preferences": { - "delete": { - "description": "Removes the authenticated user's explicit notification preference for a\ngiven `(type, channel)` combination, reverting that slot to the type's\ndefault channel set.\n\nThe `app_id` param scopes the deletion to a specific app's preference\nrow. Omit `app_id` to target the system-level (no-app) slot. Because\nthe two slots are stored independently, omitting `app_id` will not\nmatch a row that has one set, and vice versa.\n\nReturns `204 No Content` on success. Returns `404` if no preference\nexists for the given composite key.\n", - "operationId": "delete_api_v1_notification_preferences", - "parameters": [], - "responses": { - "204": { - "description": "Empty response body. A `204 No Content` status indicates the preference was deleted successfully." - }, - "401": { - "description": "Unauthorized" - }, - "403": { - "description": "App-scoped token required. Use a token scoped to the target app." - }, - "404": { - "description": "Notification preference not found" - } - }, - "summary": "Delete a notification preference", - "x-auth": [ - "publishable_key", - "bearer" - ] - }, - "get": { - "description": "Returns all explicit notification preferences belonging to the authenticated\nuser. Preferences are returned for every `(type, channel)` combination the\nuser has explicitly configured; slots that have not been overridden are not\nincluded and fall back to the type's defaults.\n\nThe recipient is derived from the authenticated viewer. You cannot retrieve\npreferences for any other user through this endpoint. All configured\npreferences — system-level and app-scoped — are returned together in the\n`data` array.\n", - "operationId": "get_api_v1_notification_preferences", - "parameters": [], - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/NotificationPreferenceList" - } - } - }, - "description": "An object with a `data` array containing all explicit notification preferences for the authenticated user." }, - "401": { - "description": "Unauthorized" - }, - "403": { - "description": "App-scoped token required. Use a token scoped to the target app." - } - }, - "summary": "List notification preferences", - "x-auth": [ - "publishable_key", - "bearer" - ] - }, - "put": { - "description": "Creates or replaces the authenticated user's notification preference for a\ngiven `(type, channel)` combination. This is an idempotent PUT: if no\npreference exists for the composite key, a new row is created; if one\nalready exists, its `enabled` flag is updated to the value you provide.\n\nThe recipient is derived from the authenticated viewer. You cannot set\npreferences for another user through this endpoint.\n\nPass `app_id` to scope the preference to a specific app's notifications —\nmost useful for the `app_*` notification type family. Omit `app_id` to\nconfigure the system-level (no-app) slot. System-level and app-scoped\npreferences are stored independently and do not overwrite each other.\n\nThe `in_app` channel is not configurable and will be rejected with a\nvalidation error if supplied.\n", - "operationId": "put_api_v1_notification_preferences", - "parameters": [], - "requestBody": { - "content": { - "application/json": { - "schema": { - "example": { - "app_id": "string", - "channel": "string", - "enabled": true, - "type": "string" - }, - "properties": { - "app_id": { - "description": "App to scope this preference to. Omit to configure the system-level (no-app) slot. App-scoped and system-level preferences are stored separately and do not affect each other.", - "example": "string", - "type": "string" - }, - "channel": { - "description": "Delivery channel to configure (e.g., `\"email\"`, `\"sms\"`). The `in_app` channel is not configurable and will be rejected with a validation error.", - "example": "string", - "type": "string" - }, - "enabled": { - "description": "Whether the specified channel should be enabled for this notification type and scope. Set to `false` to suppress delivery on this channel.", - "example": true, - "type": "boolean" - }, - "type": { - "description": "Notification type to configure. Use a builtin name (e.g., `\"app_info\"`, `\"billing_alert\"`) or a `\"custom:\"` identifier matching a NotificationType config registered in your app's bundle. Unknown type identifiers are rejected with a validation error.", - "example": "string", - "type": "string" - } - }, - "required": [ - "type", - "channel", - "enabled" - ], - "type": "object" - } + { + "description": "Exact knowledge source type to filter by, e.g. `\"knowledge/documents\"`.", + "example": "string", + "in": "query", + "name": "type", + "required": false, + "schema": { + "type": "string" } }, - "required": true - }, - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/NotificationPreference" - } - } - }, - "description": "The created or updated notification preference reflecting the new `enabled` state." - }, - "401": { - "description": "Unauthorized" - }, - "403": { - "description": "App-scoped token required. Use a token scoped to the target app.; Viewer has no recipient context (no associated user or developer account)." - }, - "422": { - "description": "Validation failed" - } - }, - "summary": "Create or update a notification preference", - "x-auth": [ - "publishable_key", - "bearer" - ] - } - }, - "/api/v1/notifications": { - "get": { - "description": "Returns a cursor-paginated list of inbox notifications for the authenticated\nuser, ordered by creation time descending (newest first). All status groups\nare included by default; pass `status` to narrow results to a specific group.\n\nEach notification's `rendered` field contains type-specific display data\nresolved at request time. Notifications whose type is no longer registered\nin the platform are rendered with `kind: \"unknown\"` rather than being omitted.\n\nPagination is forward-only: supply `after_cursor` from a previous response to\nfetch the next (older) page. The `before_cursor` field is always `null` for\nthis endpoint. Requires an app-scoped token.\n", - "operationId": "get_api_v1_notifications", - "parameters": [ { - "description": "Filter by notification status. One of `\"all\"`, `\"active\"`, `\"unread\"`, `\"read\"`, or `\"archived\"`. Defaults to `\"all\"` when omitted.", + "description": "Installation ID (`ins_...`). Returns only sources associated with this installation.", "example": "string", "in": "query", - "name": "status", + "name": "installation", "required": false, "schema": { "type": "string" } }, { - "description": "Maximum number of notifications to return per page. Defaults to 20; maximum is 100.", - "example": 1, + "description": "Agent ID (`agt_...`). Returns only sources owned by or associated with this agent.", + "example": "string", "in": "query", - "name": "limit", + "name": "agent", "required": false, "schema": { - "type": "integer" + "type": "string" } }, { - "description": "Opaque pagination cursor from a previous response's `after_cursor` field. Omit to fetch the most recent notifications.", + "description": "Organization ID (`org_...`). Returns only sources belonging to this organization. Combine with `owner_scope: \"system\"` to retrieve org-level system sources.", "example": "string", "in": "query", - "name": "after_cursor", + "name": "org", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Filter by ownership scope. One of `\"any\"` (default — returns all visible sources), `\"individual\"` (only sources owned by a user, team, or agent), or `\"system\"` (only sources with no individual owner, typically org-level).", + "example": "any", + "in": "query", + "name": "owner_scope", "required": false, "schema": { + "enum": [ + "any", + "individual", + "system" + ], "type": "string" } } @@ -38640,118 +40675,218 @@ "content": { "application/json": { "schema": { - "description": "Cursor-paginated list of notifications for the authenticated user.", + "description": "Paginated list of knowledge sources.", "example": { - "after_cursor": "string", - "before_cursor": "string", "data": [ { - "archived_at": "2024-01-01T00:00:00Z", + "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "context_installation": "cin_0aBcDeFgHiJkLmNoPqRsTu", "created_at": "2024-01-01T00:00:00Z", - "id": "ntf_0aBcDeFgHiJkLmNoPqRsTu", - "read_at": "2024-01-01T00:00:00Z", - "rendered": {}, - "status": "unread", - "type": "app_info" + "id": "cso_0aBcDeFgHiJkLmNoPqRsTu", + "metadata": { + "key": "value" + }, + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "parent_source": "cso_0aBcDeFgHiJkLmNoPqRsTu", + "payload": { + "key": "value" + }, + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "state": "active", + "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "thread": "thr_0aBcDeFgHiJkLmNoPqRsTu", + "type": "gmail", + "updated_at": "2024-01-01T00:00:00Z", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" } ], - "has_more": true + "has_next": true, + "has_prev": true, + "page": 1, + "page_size": 1, + "total_entries": 1, + "total_pages": 1 }, "properties": { - "after_cursor": { - "description": "Opaque cursor to pass as `after_cursor` on the next request to fetch older notifications. `null` when this is the last page.", - "example": "string", - "type": "string" - }, - "before_cursor": { - "description": "Always `null` — inbox pagination is forward-only and does not support fetching newer pages via cursor.", - "example": "string", - "type": "string" - }, "data": { - "description": "Array of notification objects for the current page, ordered newest first.", + "description": "Array of knowledge source objects for the current page.", "example": [ { - "archived_at": "2024-01-01T00:00:00Z", + "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "context_installation": "cin_0aBcDeFgHiJkLmNoPqRsTu", "created_at": "2024-01-01T00:00:00Z", - "id": "ntf_0aBcDeFgHiJkLmNoPqRsTu", - "read_at": "2024-01-01T00:00:00Z", - "rendered": {}, - "status": "unread", - "type": "app_info" + "id": "cso_0aBcDeFgHiJkLmNoPqRsTu", + "metadata": { + "key": "value" + }, + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "parent_source": "cso_0aBcDeFgHiJkLmNoPqRsTu", + "payload": { + "key": "value" + }, + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "state": "active", + "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "thread": "thr_0aBcDeFgHiJkLmNoPqRsTu", + "type": "gmail", + "updated_at": "2024-01-01T00:00:00Z", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" } ], "items": { - "description": "An inbox notification delivered to a recipient user. Includes type-specific render data resolved at request time.", + "description": "A knowledge source that ingests content into the knowledge base. Sources connect to external systems (e.g. Gmail, GitHub) and continuously or on-demand index items for search.", "example": { - "archived_at": "2024-01-01T00:00:00Z", + "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "context_installation": "cin_0aBcDeFgHiJkLmNoPqRsTu", "created_at": "2024-01-01T00:00:00Z", - "id": "ntf_0aBcDeFgHiJkLmNoPqRsTu", - "read_at": "2024-01-01T00:00:00Z", - "rendered": {}, - "status": "unread", - "type": "app_info" + "id": "cso_0aBcDeFgHiJkLmNoPqRsTu", + "metadata": { + "key": "value" + }, + "org": "org_0aBcDeFgHiJkLmNoPqRsTu", + "parent_source": "cso_0aBcDeFgHiJkLmNoPqRsTu", + "payload": { + "key": "value" + }, + "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "state": "active", + "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "thread": "thr_0aBcDeFgHiJkLmNoPqRsTu", + "type": "gmail", + "updated_at": "2024-01-01T00:00:00Z", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" }, "properties": { - "archived_at": { - "description": "When the recipient archived this notification. `null` if the notification has not been archived.", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "agent": { + "description": "ID of the agent that owns this source (`agt_...`). `null` if owned by a human user or team.", + "example": "agi_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "context_installation": { + "description": "ID of the context installation that provisioned this source (`cin_...`). `null` when the source was created directly rather than through an installation.", + "example": "cin_0aBcDeFgHiJkLmNoPqRsTu", "type": "string" }, "created_at": { - "description": "When the notification was sent (ISO 8601).", + "description": "When this knowledge source was created (ISO 8601).", "example": "2024-01-01T00:00:00Z", "format": "date-time", "type": "string" }, "id": { - "description": "Notification ID (`ntf_...`).", - "example": "ntf_0aBcDeFgHiJkLmNoPqRsTu", + "description": "Knowledge source ID (`cso_...`).", + "example": "cso_0aBcDeFgHiJkLmNoPqRsTu", "type": "string" }, - "read_at": { - "description": "When the recipient marked this notification read. `null` if the notification has not been read.", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", + "metadata": { + "description": "Arbitrary key-value metadata attached to this source. Useful for storing caller-defined labels or references.", + "example": { + "key": "value" + }, + "type": "object" + }, + "org": { + "description": "ID of the organization this source belongs to (`org_...`). `null` if not scoped to an org.", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", "type": "string" }, - "rendered": { - "description": "Type-specific render spec resolved at request time. All types include `title`, `kind`, and `actions`; custom types may add their own keys. Notifications whose type is no longer registered render with `kind: \"unknown\"`.", - "example": {}, + "parent_source": { + "description": "ID of the parent knowledge source (`cso_...`) when this source was derived from another. `null` for top-level sources.", + "example": "cso_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "payload": { + "description": "Type-specific configuration object. The keys depend on the source `type`; see the create endpoint for the expected shape per type.", + "example": { + "key": "value" + }, "type": "object" }, - "status": { - "description": "Current read state of the notification. One of `\"unread\"`, `\"read\"`, or `\"archived\"`.", - "example": "unread", + "sandbox": { + "description": "ID of the developer sandbox this source is scoped to (`sbx_...`). `null` outside sandbox contexts.", + "example": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "state": { + "description": "Current lifecycle state of the source. One of `\"active\"` (ingestion running normally) or `\"paused\"` (ingestion suspended).", + "example": "active", + "type": "string" + }, + "team": { + "description": "ID of the team that owns this source (`tea_...`). `null` if owned by a user, agent, or org.", + "example": "tem_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "thread": { + "description": "ID of the chat thread this source is associated with (`thr_...`). `null` when not thread-scoped.", + "example": "thr_0aBcDeFgHiJkLmNoPqRsTu", "type": "string" }, "type": { - "description": "Notification type slug, e.g. `\"app_info\"` for a built-in type or `\"custom:deploy_complete\"` for a custom type.", - "example": "app_info", + "description": "Source type identifier (e.g. `\"gmail\"`, `\"github_activity\"`). Determines the shape of `payload` and the ingestion behavior.", + "example": "gmail", + "type": "string" + }, + "updated_at": { + "description": "When this knowledge source 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 source (`usr_...`). `null` if owned by a team, agent, or org.", + "example": "usr_0aBcDeFgHiJkLmNoPqRsTu", "type": "string" } }, "required": [ "id", "type", - "status", - "rendered", - "created_at" + "state" ], "type": "object" }, "type": "array" }, - "has_more": { - "description": "`true` if additional (older) notifications exist beyond this page; `false` if this is the last page.", + "has_next": { + "description": "`true` if a subsequent page exists, `false` if this is the last page.", + "example": true, + "type": "boolean" + }, + "has_prev": { + "description": "`true` if a previous page exists, `false` if this is the first page.", "example": true, "type": "boolean" + }, + "page": { + "description": "Current page number.", + "example": 1, + "type": "integer" + }, + "page_size": { + "description": "Number of results returned per page.", + "example": 1, + "type": "integer" + }, + "total_entries": { + "description": "Total number of knowledge sources matching the query across all pages.", + "example": 1, + "type": "integer" + }, + "total_pages": { + "description": "Total number of pages available.", + "example": 1, + "type": "integer" } }, "required": [ "data", - "has_more" + "page", + "page_size", + "total_entries", + "total_pages", + "has_next", + "has_prev" ], "type": "object" } @@ -38759,32 +40894,6 @@ }, "description": "Successful response" }, - "400": { - "description": "Bad request; Invalid cursor" - }, - "401": { - "description": "Unauthorized" - }, - "403": { - "description": "App-scoped token required. Use a token scoped to the target app." - } - }, - "summary": "List a user's notifications", - "x-auth": [ - "publishable_key", - "bearer" - ] - } - }, - "/api/v1/notifications/read_all": { - "post": { - "description": "Marks every `\"unread\"` notification belonging to the authenticated user as\n`\"read\"` in a single operation. Notifications that are already `\"read\"` or\n`\"archived\"` are not affected.\n\nThis call is safe to retry — if there are no unread notifications, it\nsucceeds without error. Requires an app-scoped token. Returns 204 No Content\non success.\n", - "operationId": "post_api_v1_notifications_read_all", - "parameters": [], - "responses": { - "204": { - "description": "No content" - }, "401": { "description": "Unauthorized" }, @@ -38792,53 +40901,90 @@ "description": "App-scoped token required. Use a token scoped to the target app." } }, - "summary": "Mark all notifications as read", + "summary": "List knowledge sources", "x-auth": [ "publishable_key", "bearer" ] - } - }, - "/api/v1/notifications/send": { + }, "post": { - "description": "Delivers a custom-typed notification to one of the calling app's users.\nApps define notification types by declaring `NotificationType` config objects\nin their bundle (one per `lookup_key`). Supply the type as\n`\"custom:\"` and provide a `data` map that is merged with\nplatform-provided context to render the notification's display fields.\n\nOnly app-scoped tokens may call this endpoint — user tokens are rejected with\n403. The app scope is stamped onto the notification automatically; an app\ncannot target recipients outside its tenant. Built-in platform types such as\n`\"app_info\"` and `\"billing_alert\"` are not accepted here.\n\nPass `idempotency_key` to deduplicate sends. If you call this endpoint twice\nwith the same `idempotency_key` for the same recipient, the second call\nreturns the original notification without creating a duplicate. The key is\nscoped to the calling app, so the same raw key used by different apps cannot\ncollide.\n", - "operationId": "post_api_v1_notifications_send", + "description": "Creates a new knowledge source of the requested type and returns the created object.\n\nOnly types listed by `GET /api/v1/knowledge_sources/kinds` may be created through this\nendpoint. Other source types — such as `webhook/inbound`, `connectors/*/emails`, and\n`thread/messages` — are provisioned automatically by server-driven flows (webhook\nauto-provisioning, installation activation, connector lifecycle events) and cannot be\ncreated directly via the API.\n\nExactly one of `team`, `user`, `agent`, or `org` must identify the owner of the new\nsource. Omit `org` when an individual owner (`team`, `user`, or `agent`) is supplied;\ninclude `org` alone for org-level system-owned sources.\n", + "operationId": "post_api_v1_knowledge_sources", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "example": { - "data": {}, - "idempotency_key": "string", + "agent": "string", + "metadata": { + "key": "value" + }, + "org": "string", + "parent_source": "string", + "payload": {}, + "state": "string", + "team": "string", + "thread": "string", "type": "string", "user": "string" }, "properties": { - "data": { - "description": "Arbitrary key-value payload merged with platform-provided context (recipient, app, org, brand) when rendering the notification's display fields. Defaults to an empty object when omitted.", - "example": {}, - "type": "object" - }, - "idempotency_key": { - "description": "Optional deduplication key. A second call with the same `idempotency_key` for the same recipient returns the originally-created notification without inserting a new record. Scoped per calling app.", + "agent": { + "description": "Agent ID (`agt_...`) that owns this source. Mutually exclusive with `team` and `user`.", "example": "string", "type": "string" }, - "type": { - "description": "Custom notification type identifier in the form `\"custom:\"`, where `` matches a `NotificationType` config declared in the calling app's bundle.", - "example": "string", + "metadata": { + "description": "Arbitrary key-value metadata to attach to the source. Returned as-is on reads.", + "example": { + "key": "value" + }, + "type": "object" + }, + "org": { + "description": "Organization ID (`org_...`). Required for system-owned sources that have no individual owner (`team`, `user`, or `agent`).", + "example": "string", + "type": "string" + }, + "parent_source": { + "description": "Parent knowledge source ID (`ksrc_...`). Use to create a child source.", + "example": "string", + "type": "string" + }, + "payload": { + "description": "Type-specific configuration for the source. Shape depends on `type`.", + "example": {}, + "type": "object" + }, + "state": { + "description": "Initial state of the source. One of `\"active\"` (default) or `\"paused\"`. Paused sources do not trigger ingestion automatically.", + "example": "string", + "type": "string" + }, + "team": { + "description": "Team ID (`team_...`) that owns this source. Mutually exclusive with `user` and `agent`.", + "example": "string", + "type": "string" + }, + "thread": { + "description": "Thread ID (`thr_...`) to associate this source with, if applicable.", + "example": "string", + "type": "string" + }, + "type": { + "description": "Knowledge source type. Must be one of the values returned by `GET /api/v1/knowledge_sources/kinds`.", + "example": "string", "type": "string" }, "user": { - "description": "Recipient user ID (`usr_...`). Must be a member of the calling app's tenant.", + "description": "User ID (`usr_...`) that owns this source. Mutually exclusive with `team` and `agent`.", "example": "string", "type": "string" } }, "required": [ - "type", - "user" + "type" ], "type": "object" } @@ -38847,18 +40993,15 @@ "required": true }, "responses": { - "200": { + "201": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Notification" + "$ref": "#/components/schemas/KnowledgeSource" } } }, - "description": "The created notification, or the existing notification when deduplicated by `idempotency_key`." - }, - "400": { - "description": "Bad request" + "description": "The newly created knowledge source." }, "401": { "description": "Unauthorized" @@ -38866,49 +41009,35 @@ "403": { "description": "App-scoped token required. Use a token scoped to the target app.; Forbidden" }, - "404": { - "description": "User not found" - }, "422": { - "description": "Invalid parameters; No NotificationType config matched this `custom:` in the calling app's bundle." + "description": "Invalid parameters; Validation failed" + }, + "502": { + "description": "Service unavailable" } }, - "summary": "Send a custom notification to a user", + "summary": "Create a knowledge source", "x-auth": [ "publishable_key", "bearer" ] } }, - "/api/v1/notifications/unread_count": { + "/api/v1/knowledge_sources/kinds": { "get": { - "description": "Returns the total number of `\"unread\"` notifications for the authenticated\nuser. Useful for displaying a badge or indicator in your UI without\nfetching the full notification list.\n\nNotifications with `\"read\"` or `\"archived\"` status are not included in the\ncount. Requires an app-scoped token.\n", - "operationId": "get_api_v1_notifications_unread_count", + "description": "Returns the fixed set of knowledge source types that can be created directly via\n`POST /api/v1/knowledge_sources`. Use this endpoint to discover valid values for the\n`type` param before calling the create endpoint.\n\nSource kinds populated by server-driven flows — such as `webhook/inbound`,\n`connectors/*/emails`, and `thread/messages` — are intentionally excluded from this\nlist, as they cannot be created through the API.\n", + "operationId": "get_api_v1_knowledge_sources_kinds", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { - "description": "Object containing the count of unread notifications for the authenticated user.", - "example": { - "count": 1 - }, - "properties": { - "count": { - "description": "Total number of notifications with `\"unread\"` status belonging to the authenticated user.", - "example": 1, - "type": "integer" - } - }, - "required": [ - "count" - ], - "type": "object" + "$ref": "#/components/schemas/KnowledgeSourceKindListResponse" } } }, - "description": "Successful response" + "description": "List of knowledge source kinds available for creation via the API." }, "401": { "description": "Unauthorized" @@ -38917,23 +41046,23 @@ "description": "App-scoped token required. Use a token scoped to the target app." } }, - "summary": "Get the unread notification count", + "summary": "List creatable knowledge source kinds", "x-auth": [ "publishable_key", "bearer" ] } }, - "/api/v1/notifications/{notification}/archive": { - "post": { - "description": "Moves a notification to `\"archived\"` status regardless of whether it is\ncurrently `\"unread\"` or `\"read\"`. Archived notifications are excluded from\nthe default inbox view but remain retrievable by passing `status: \"archived\"`\nto the list endpoint.\n\nThe authenticated user must own the notification. Passing a notification ID\nthat belongs to a different user returns a 404. If the notification is\nalready archived this call succeeds without error (idempotent).\n\nRequires an app-scoped token. Returns 204 No Content on success.\n", - "operationId": "post_api_v1_notifications__notification_archive", + "/api/v1/knowledge_sources/{source}": { + "delete": { + "description": "Permanently deletes the knowledge source identified by `source`. This action is\nirreversible — all documents, embeddings, and ingestion history associated with the\nsource are removed.\n\nThe authenticated caller must own the source or have sufficient permissions within its\nparent organization. Returns `204 No Content` on success.\n", + "operationId": "delete_api_v1_knowledge_sources__source", "parameters": [ { - "description": "Notification ID (`ntf_...`) to archive. Must belong to the authenticated user.", + "description": "Knowledge source ID (`ksrc_...`) to delete.", "example": "string", "in": "path", - "name": "notification", + "name": "source", "required": true, "schema": { "type": "string" @@ -38942,35 +41071,33 @@ ], "responses": { "204": { - "description": "No content" + "description": "Empty response. The source has been permanently deleted." }, "401": { "description": "Unauthorized" }, "403": { - "description": "App-scoped token required. Use a token scoped to the target app." + "description": "App-scoped token required. Use a token scoped to the target app.; Forbidden" }, "404": { - "description": "Notification not found" + "description": "Knowledge source not found" } }, - "summary": "Archive a notification", + "summary": "Delete a knowledge source", "x-auth": [ "publishable_key", "bearer" ] - } - }, - "/api/v1/notifications/{notification}/read": { - "post": { - "description": "Transitions a notification from `\"unread\"` to `\"read\"` status. If the\nnotification is already `\"read\"` or `\"archived\"`, the call succeeds without\nchanging its status (idempotent).\n\nThe authenticated user must own the notification. Passing a notification ID\nthat belongs to a different user returns a 404. Requires an app-scoped token.\nReturns 204 No Content on success.\n", - "operationId": "post_api_v1_notifications__notification_read", + }, + "get": { + "description": "Returns the knowledge source identified by `source`. The authenticated caller must have\naccess to the source's parent organization or be the individual owner of the source.\n\nUse the list endpoint to retrieve many sources at once or to discover sources by type\nor owner.\n", + "operationId": "get_api_v1_knowledge_sources__source", "parameters": [ { - "description": "Notification ID (`ntf_...`) to mark as read. Must belong to the authenticated user.", + "description": "Knowledge source ID (`ksrc_...`) to retrieve.", "example": "string", "in": "path", - "name": "notification", + "name": "source", "required": true, "schema": { "type": "string" @@ -38978,8 +41105,15 @@ } ], "responses": { - "204": { - "description": "No content" + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/KnowledgeSource" + } + } + }, + "description": "The requested knowledge source." }, "401": { "description": "Unauthorized" @@ -38988,226 +41122,290 @@ "description": "App-scoped token required. Use a token scoped to the target app." }, "404": { - "description": "Notification not found" + "description": "Knowledge source not found" } }, - "summary": "Mark a notification as read", + "summary": "Retrieve a knowledge source", "x-auth": [ "publishable_key", "bearer" ] - } - }, - "/api/v1/notifications/{notification}/unarchive": { - "post": { - "description": "Restores an `\"archived\"` notification to its previous active status:\n`\"read\"` if the notification had been read before archiving, or `\"unread\"`\notherwise. The notification will appear again in the default inbox view.\n\nThe authenticated user must own the notification. Passing a notification ID\nthat belongs to a different user returns a 404. If the notification is not\ncurrently archived this call succeeds without changing its status (idempotent).\nRequires an app-scoped token. Returns 204 No Content on success.\n", - "operationId": "post_api_v1_notifications__notification_unarchive", + }, + "patch": { + "description": "Updates the mutable fields of an existing knowledge source and returns the updated\nobject. Only fields provided in the request body are changed; omitted fields retain\ntheir current values.\n\nYou can update the type-specific `payload`, the `metadata` map, and the `state`. To\npause a source and prevent automatic ingestion, set `state` to `\"paused\"`. To resume,\nset it back to `\"active\"`.\n", + "operationId": "patch_api_v1_knowledge_sources__source", "parameters": [ { - "description": "Notification ID (`ntf_...`) to unarchive. Must belong to the authenticated user.", + "description": "Knowledge source ID (`ksrc_...`) to update.", "example": "string", "in": "path", - "name": "notification", + "name": "source", "required": true, "schema": { "type": "string" } } ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "example": { + "metadata": { + "key": "value" + }, + "payload": {}, + "state": "string" + }, + "properties": { + "metadata": { + "description": "Arbitrary key-value metadata to attach to the source. Replaces the entire existing `metadata` map when provided.", + "example": { + "key": "value" + }, + "type": "object" + }, + "payload": { + "description": "Type-specific configuration to replace on the source. Shape depends on the source `type`. Replaces the entire existing `payload` when provided.", + "example": {}, + "type": "object" + }, + "state": { + "description": "Desired state of the source. One of `\"active\"` or `\"paused\"`. Paused sources do not trigger ingestion automatically.", + "example": "string", + "type": "string" + } + }, + "type": "object" + } + } + }, + "required": true + }, "responses": { - "204": { - "description": "No content" + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/KnowledgeSource" + } + } + }, + "description": "The updated knowledge source." }, "401": { "description": "Unauthorized" }, "403": { - "description": "App-scoped token required. Use a token scoped to the target app." + "description": "App-scoped token required. Use a token scoped to the target app.; Forbidden" }, "404": { - "description": "Notification not found" + "description": "Knowledge source not found" + }, + "422": { + "description": "Invalid parameters; Validation failed" + }, + "502": { + "description": "Service unavailable" } }, - "summary": "Unarchive a notification", + "summary": "Update a knowledge source", "x-auth": [ "publishable_key", "bearer" ] } }, - "/api/v1/orgs": { - "get": { - "description": "Returns a paginated list of organizations within the authenticated app scope,\noptionally filtered by a free-text search term matched against name, slug, and\ndomain (case-insensitive). Results are ordered by relevance when a search term\nis provided, and by creation time descending otherwise.\n\nThe response includes only public-facing organization fields: ID, name, domain,\nand logo. Use the developer-scoped org endpoints to access full organization\nrecords.\n\nPagination is offset-based. Pass `page` and `page_size` to navigate through\nresults. The `has_next` and `has_prev` fields indicate whether adjacent pages\nexist.\n", - "operationId": "get_api_v1_orgs", + "/api/v1/knowledge_sources/{source}/ingest": { + "post": { + "description": "Starts an ingestion run on the specified knowledge source and returns the ingestion\nobject. Exactly one of two modes must be chosen per request:\n\n**Push mode** (`file` or `content`) — available for `knowledge/documents` sources only.\nSupply the document bytes either as a reference to an already-uploaded file (`file`) or\nas an inline blob (`content`). The runner stores the bytes and indexes the resulting\ndocument. `title` and `metadata` are persisted on the document in push mode.\n\n**Pull mode** (`pull: true`) — re-triggers ingestion using the source's own configured\ndata. Use this to re-scrape a `scrape/site`, re-fetch a `web/link`, or re-process a\n`file/document`. Not valid for `knowledge/documents` (which has no upstream — push new\nbytes instead) or for source kinds populated by server-driven flows. `title` and\n`metadata` are ignored in pull mode.\n\nIf an ingestion is already active for the source, the existing ingestion is returned\nrather than creating a duplicate.\n", + "operationId": "post_api_v1_knowledge_sources__source_ingest", "parameters": [ { - "description": "Free-text search term matched against organization name, slug, and domain (case-insensitive). Omit to return all organizations in the app.", + "description": "Knowledge source ID (`ksrc_...`) to ingest.", "example": "string", - "in": "query", - "name": "search", - "required": false, + "in": "path", + "name": "source", + "required": true, "schema": { "type": "string" } - }, - { - "description": "Page number to retrieve, starting at `1`. Defaults to `1` when omitted.", - "example": 1, - "in": "query", - "name": "page", - "required": false, - "schema": { - "type": "integer" - } - }, - { - "description": "Number of organizations to return per page. Defaults to `25`; maximum is `100`.", - "example": 1, - "in": "query", - "name": "page_size", - "required": false, - "schema": { - "type": "integer" - } } ], - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "description": "Paginated list of organizations matching the query.", - "example": { - "data": [ - { - "domain": "acme.com", - "id": "org_0aBcDeFgHiJkLmNoPqRsTu", - "name": "Example Name" - } - ], - "has_next": true, - "has_prev": true, - "page": 1, - "page_size": 1, - "total_entries": 1, - "total_pages": 1 + "requestBody": { + "content": { + "application/json": { + "schema": { + "example": { + "content": { + "content_type": "application/json", + "data": "string", + "data_encoding": "string", + "filename": "string" }, - "properties": { - "data": { - "description": "Array of organization objects for the current page.", - "example": [ - { - "domain": "acme.com", - "id": "org_0aBcDeFgHiJkLmNoPqRsTu", - "name": "Example Name" - } - ], - "items": { - "description": "A minimal organization object returned on authenticated endpoints. Exposes only the fields safe for any authenticated user: identity, display name, primary domain, and logo.", - "example": { - "domain": "acme.com", - "id": "org_0aBcDeFgHiJkLmNoPqRsTu", - "name": "Example Name" - }, - "properties": { - "domain": { - "description": "Primary domain associated with the organization, e.g. `\"acme.com\"`.", - "example": "acme.com", - "type": "string" - }, - "id": { - "description": "Organization ID (`org_...`).", - "example": "org_0aBcDeFgHiJkLmNoPqRsTu", - "type": "string" - }, - "name": { - "description": "Display name of the organization.", - "example": "Example Name", - "type": "string" - } - }, - "required": [ - "id", - "name", - "domain" - ], - "type": "object" - }, - "type": "array" - }, - "has_next": { - "description": "`true` when a subsequent page exists; `false` on the last page.", - "example": true, - "type": "boolean" - }, - "has_prev": { - "description": "`true` when a previous page exists; `false` on the first page.", - "example": true, - "type": "boolean" - }, - "page": { - "description": "The current page number returned.", - "example": 1, - "type": "integer" + "dedupe": true, + "file": "string", + "metadata": { + "key": "value" + }, + "pull": true, + "title": "Example Title" + }, + "properties": { + "content": { + "description": "Inline document bytes to push to the source. Mutually exclusive with `file` and `pull`.", + "example": { + "content_type": "application/json", + "data": "string", + "data_encoding": "string", + "filename": "string" }, - "page_size": { - "description": "The number of results per page used for this response.", - "example": 1, - "type": "integer" + "properties": { + "content_type": { + "description": "MIME type of the content, e.g. `\"application/pdf\"` or `\"text/plain\"`.", + "example": "application/json", + "type": "string" + }, + "data": { + "description": "The raw document bytes. When `data_encoding` is `\"base64\"`, provide the base64-encoded representation of the binary content.", + "example": "string", + "type": "string" + }, + "data_encoding": { + "description": "Encoding format of `data`. One of `\"raw\"` (default, plain text) or `\"base64\"` (binary content such as images or PDFs, decoded server-side before storage).", + "example": "string", + "type": "string" + }, + "filename": { + "description": "Original filename for the document, e.g. `\"report.pdf\"`.", + "example": "string", + "type": "string" + } }, - "total_entries": { - "description": "Total number of organizations matching the query across all pages.", - "example": 1, - "type": "integer" + "required": [ + "data" + ], + "type": "object" + }, + "dedupe": { + "description": "When `true`, reuse the source's existing document if the pushed content is byte-identical to it, instead of creating a duplicate. The reused document keeps its chunks and embeddings, and `title`/`metadata` from this request are still applied to it. Content that differs in any way always creates a new document. Defaults to `false`, which creates a new document on every push. Push mode only — not valid with `pull: true`. Check `metadata.document_reused` on the returned ingestion to see whether a document was actually reused.", + "example": true, + "type": "boolean" + }, + "file": { + "description": "ID of an already-uploaded file (`fil_...`). The runner reads filename and content type from the stored file. Upload the file via `POST /v1/files` first. Mutually exclusive with `content` and `pull`.", + "example": "string", + "type": "string" + }, + "metadata": { + "description": "Arbitrary key-value metadata to attach to the ingested document. Applied in push mode only; ignored when `pull: true`.", + "example": { + "key": "value" }, - "total_pages": { - "description": "Total number of pages for the current query and page size.", - "example": 1, - "type": "integer" - } + "type": "object" }, - "required": [ - "data" - ], - "type": "object" + "pull": { + "description": "When `true`, re-triggers ingestion using the source's own configured data. Re-scrapes a `scrape/site`, re-fetches a `web/link`, or re-processes a `file/document`. Mutually exclusive with `file` and `content`. Not valid for `knowledge/documents` sources.", + "example": true, + "type": "boolean" + }, + "title": { + "description": "Display title for the ingested document. Applied in push mode only; ignored when `pull: true`.", + "example": "Example Title", + "type": "string" + } + }, + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "201": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContextIngestion" } } }, - "description": "Successful response" + "description": "The created ingestion, or an existing active ingestion if one is already running." }, "401": { "description": "Unauthorized" }, "403": { - "description": "App-scoped token required. Use a token scoped to the target app." + "description": "App-scoped token required. Use a token scoped to the target app.; Forbidden" + }, + "404": { + "description": "Knowledge source not found" + }, + "422": { + "description": "Invalid parameters" + }, + "429": { + "description": "Too many requests" } }, - "summary": "Search organizations", + "summary": "Trigger ingestion on a knowledge source", "x-auth": [ "publishable_key", "bearer" ] } }, - "/api/v1/private_service_definitions/{app_id}/{private_service_id}": { + "/api/v1/kv": { "get": { - "description": "Returns the canonical callable definition authorized by an enrollment token.", - "operationId": "get_api_v1_private_service_definitions__app_id__private_service_id", + "description": "Returns key-value storage entries in one of two modes depending on the caller's\nauth scope.\n\n**User-JWT callers** receive a flat list of all their own entries with no\npagination fields. The `page`, `page_size`, `user`, `user_search`, and `key`\nparams are ignored.\n\n**Developer and server-to-server callers** receive a page-based paginated\nresponse across all users within the caller's app. Use `user` to scope results\nto a single user, `user_search` to do a substring match on email or full name,\nand `key` to filter entries whose key starts with the given prefix. Results are\nordered by creation time descending.\n", + "operationId": "get_api_v1_kv", "parameters": [ { + "description": "Page number to retrieve. Applies to developer and server-to-server callers only. Defaults to 1.", + "example": 1, + "in": "query", + "name": "page", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "description": "Number of entries per page. Applies to developer and server-to-server callers only. Defaults to 25; maximum is 100.", + "example": 1, + "in": "query", + "name": "page_size", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "description": "Filter results to entries belonging to this user ID. Applies to developer and server-to-server callers only.", "example": "string", - "in": "path", - "name": "app_id", - "required": true, + "in": "query", + "name": "user", + "required": false, "schema": { "type": "string" } }, { + "description": "Substring match against user email address and full name. Applies to developer and server-to-server callers only.", "example": "string", - "in": "path", - "name": "private_service_id", - "required": true, + "in": "query", + "name": "user_search", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Prefix filter on the storage key. Returns only entries whose key starts with this string. Applies to developer and server-to-server callers only.", + "example": "string", + "in": "query", + "name": "key", + "required": false, "schema": { "type": "string" } @@ -39218,117 +41416,61 @@ "content": { "application/json": { "schema": { - "format": "binary", - "type": "string" + "$ref": "#/components/schemas/KeyValueStorageEntryPage" } } }, - "description": "Raw content" + "description": "Key-value storage entries for the current page, with pagination metadata for developer and server-to-server callers." }, - "401": { - "description": "Invalid enrollment token" + "400": { + "description": "Bad request" }, - "404": { - "description": "Not found" - }, - "503": { - "description": "Private service control is unavailable" - } - }, - "summary": "Download an enrolled private service definition" - } - }, - "/api/v1/private_service_enrollments": { - "get": { - "operationId": "get_api_v1_private_service_enrollments", - "parameters": [ - { - "description": "Organization ID or slug. Required for developer and server callers.", - "example": "string", - "in": "query", - "name": "org", - "required": false, - "schema": { - "type": "string" - } - }, - { - "description": "Page number. Defaults to 1.", - "example": 1, - "in": "query", - "name": "page", - "required": false, - "schema": { - "type": "integer" - } - }, - { - "description": "Results per page. Defaults to 25; maximum is 100.", - "example": 1, - "in": "query", - "name": "page_size", - "required": false, - "schema": { - "type": "integer" - } - } - ], - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PrivateServiceEnrollmentPage" - } - } - }, - "description": "Successful response" - }, - "400": { - "description": "Bad request" + "401": { + "description": "Unauthorized" }, "403": { - "description": "Forbidden" - }, - "404": { - "description": "Not found" - }, - "503": { - "description": "Private service control is unavailable" + "description": "App-scoped token required. Use a token scoped to the target app." } }, - "summary": "List private service enrollments", + "summary": "List key-value storage entries", "x-auth": [ "publishable_key", "bearer" ] }, "post": { - "description": "Creates or safely replaces an unreserved one-time connector enrollment token.", - "operationId": "post_api_v1_private_service_enrollments", + "description": "Creates a new key-value storage entry for the target user under the given key.\nThe key must not already exist for this user; use the upsert endpoint to create\nor overwrite in a single call.\n\nEnd-user (user-JWT) callers always write to their own storage. Developer and\nserver-to-server callers must supply a `user` param identifying the target user\nwithin their app's scope. Attempting to write for a user in a different app\nreturns 404.\n", + "operationId": "post_api_v1_kv", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "example": { - "org": "string", - "private_service": "string" + "key": "string", + "user": "string", + "value": "string" }, "properties": { - "org": { - "description": "Organization ID or slug. Required for developer and server callers.", + "key": { + "description": "Storage key for the entry. Must be a non-empty string unique to this user.", "example": "string", "type": "string" }, - "private_service": { - "description": "Private service ID (`pvs_...`).", + "user": { + "description": "Target user ID. Required when calling as a developer or with a server-to-server key; ignored for end-user callers.", + "example": "string", + "type": "string" + }, + "value": { + "description": "Value to store under `key`. Must be a non-empty string.", "example": "string", "type": "string" } }, "required": [ - "private_service" + "key", + "value" ], "type": "object" } @@ -39341,54 +41483,45 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CreatedPrivateServiceEnrollment" + "$ref": "#/components/schemas/KeyValueStorageEntry" } } }, - "description": "Successful response" + "description": "The newly created key-value storage entry." }, "400": { "description": "Bad request" }, + "401": { + "description": "Unauthorized" + }, "403": { - "description": "Forbidden" + "description": "Forbidden; App-scoped token required. Use a token scoped to the target app." }, "404": { - "description": "Not found" - }, - "409": { - "description": "Conflict" + "description": "User not found" }, - "503": { - "description": "Private service control is unavailable" + "422": { + "description": "Invalid parameters" } }, - "summary": "Create a private service enrollment", + "summary": "Create a key-value storage entry", "x-auth": [ "publishable_key", "bearer" ] } }, - "/api/v1/private_service_enrollments/{private_service_enrollment_id}": { - "get": { - "operationId": "get_api_v1_private_service_enrollments__private_service_enrollment_id", + "/api/v1/kv/{key}": { + "delete": { + "description": "Permanently deletes the key-value storage entry identified by `key` for the\ntarget user. Returns 204 No Content on success and 404 if the entry does not\nexist.\n\nEnd-user (user-JWT) callers can only delete entries they own. Developer and\nserver-to-server callers must supply a `user` param identifying the target user\nwithin their app's scope.\n", + "operationId": "delete_api_v1_kv__key", "parameters": [ { - "description": "Organization ID or slug. Required for developer and server callers.", - "example": "string", - "in": "query", - "name": "org", - "required": false, - "schema": { - "type": "string" - } - }, - { - "description": "Canonical certificate-bound service identity.", + "description": "Storage key of the entry to delete. Must be a non-empty string.", "example": "string", "in": "path", - "name": "private_service_enrollment_id", + "name": "key", "required": true, "schema": { "type": "string" @@ -39396,68 +41529,50 @@ } ], "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PrivateServiceEnrollment" - } - } - }, - "description": "Successful response" + "204": { + "description": "Empty response body. HTTP 204 No Content on success." }, "400": { "description": "Bad request" }, + "401": { + "description": "Unauthorized" + }, "403": { - "description": "Forbidden" + "description": "Forbidden; App-scoped token required. Use a token scoped to the target app." }, "404": { - "description": "Not found" - }, - "503": { - "description": "Private service control is unavailable" + "description": "Entry not found; User not found" } }, - "summary": "Retrieve a private service enrollment", + "summary": "Delete a key-value storage entry", "x-auth": [ "publishable_key", "bearer" ] - } - }, - "/api/v1/private_services": { + }, "get": { - "operationId": "get_api_v1_private_services", + "description": "Returns the key-value storage entry identified by `key` for the target user.\nReturns 404 if no entry exists for that key.\n\nEnd-user (user-JWT) callers retrieve entries from their own storage. Developer\nand server-to-server callers must supply a `user` param identifying the target\nuser within their app's scope.\n", + "operationId": "get_api_v1_kv__key", "parameters": [ { - "description": "Organization ID or slug. Required for developer and server callers.", + "description": "Storage key of the entry to retrieve. Must be a non-empty string.", "example": "string", - "in": "query", - "name": "org", - "required": false, + "in": "path", + "name": "key", + "required": true, "schema": { "type": "string" } }, { - "description": "Page number. Defaults to 1.", - "example": 1, - "in": "query", - "name": "page", - "required": false, - "schema": { - "type": "integer" - } - }, - { - "description": "Results per page. Defaults to 25; maximum is 100.", - "example": 1, + "description": "Target user ID. Required when calling as a developer or with a server-to-server key; ignored for end-user callers.", + "example": "string", "in": "query", - "name": "page_size", + "name": "user", "required": false, "schema": { - "type": "integer" + "type": "string" } } ], @@ -39466,108 +41581,68 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PrivateServicePage" + "$ref": "#/components/schemas/KeyValueStorageEntry" } } }, - "description": "Successful response" + "description": "The key-value storage entry for the given key." }, "400": { "description": "Bad request" }, + "401": { + "description": "Unauthorized" + }, "403": { - "description": "Forbidden" + "description": "Forbidden; App-scoped token required. Use a token scoped to the target app." }, "404": { - "description": "Not found" - }, - "503": { - "description": "Private service control is unavailable" + "description": "Entry not found; User not found" } }, - "summary": "List private services", + "summary": "Retrieve a key-value storage entry", "x-auth": [ "publishable_key", "bearer" ] }, - "post": { - "description": "Creates one immutable private service in the selected organization.", - "operationId": "post_api_v1_private_services", - "parameters": [], + "put": { + "description": "Creates a new key-value storage entry for the given `key`, or overwrites the\nvalue if an entry already exists. This is the idempotent alternative to the\ncreate endpoint: safe to call regardless of whether the key already exists.\n\nEnd-user (user-JWT) callers always write to their own storage. Developer and\nserver-to-server callers must supply a `user` param identifying the target user\nwithin their app's scope. Attempting to write for a user in a different app\nreturns 404.\n", + "operationId": "put_api_v1_kv__key", + "parameters": [ + { + "description": "Storage key to create or overwrite. Must be a non-empty string.", + "example": "string", + "in": "path", + "name": "key", + "required": true, + "schema": { + "type": "string" + } + } + ], "requestBody": { "content": { "application/json": { "schema": { "example": { - "functions": [ - { - "description": "An example description.", - "input_schema": {}, - "name": "Example Name", - "output_schema": {} - } - ], - "org": "string" + "user": "string", + "value": "string" }, "properties": { - "functions": { - "description": "Complete callable contracts. Input schemas are required; output schemas are optional.", - "example": [ - { - "description": "An example description.", - "input_schema": {}, - "name": "Example Name", - "output_schema": {} - } - ], - "items": { - "description": "A documented callable operation exposed by a private service.", - "example": { - "description": "An example description.", - "input_schema": {}, - "name": "Example Name", - "output_schema": {} - }, - "properties": { - "description": { - "description": "Human-readable guidance describing when and why to call the operation.", - "example": "An example description.", - "type": "string" - }, - "input_schema": { - "description": "JSON Schema Draft 7 object describing the operation's argument object.", - "example": {}, - "type": "object" - }, - "name": { - "description": "Stable operation name used when invoking the private service.", - "example": "Example Name", - "type": "string" - }, - "output_schema": { - "description": "Optional JSON Schema Draft 7 object describing the successful result.", - "example": {}, - "type": "object" - } - }, - "required": [ - "name", - "description", - "input_schema" - ], - "type": "object" - }, - "type": "array" + "user": { + "description": "Target user ID. Required when calling as a developer or with a server-to-server key; ignored for end-user callers.", + "example": "string", + "type": "string" }, - "org": { - "description": "Organization ID or slug. Required for developer and server callers.", + "value": { + "description": "New value to store under `key`. Must be a non-empty string. Replaces any existing value.", "example": "string", "type": "string" } }, "required": [ - "functions" + "value" ], "type": "object" } @@ -39580,137 +41655,129 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PrivateService" + "$ref": "#/components/schemas/KeyValueStorageEntry" } } }, - "description": "The newly created private service." + "description": "The created or updated key-value storage entry." }, "400": { "description": "Bad request" }, + "401": { + "description": "Unauthorized" + }, "403": { - "description": "Forbidden" + "description": "Forbidden; App-scoped token required. Use a token scoped to the target app." }, "404": { - "description": "Not found" - }, - "409": { - "description": "Conflict" + "description": "User not found" }, - "503": { - "description": "Private service control is unavailable" + "422": { + "description": "Invalid parameters" } }, - "summary": "Create a private service", + "summary": "Create or update a key-value storage entry", "x-auth": [ "publishable_key", "bearer" - ] + ], + "x-sdk-name": "upsert" } }, - "/api/v1/private_services/{private_service_id}": { - "get": { - "operationId": "get_api_v1_private_services__private_service_id", - "parameters": [ - { - "description": "Organization ID or slug. Required for developer and server callers.", - "example": "string", - "in": "query", - "name": "org", - "required": false, - "schema": { - "type": "string" - } + "/api/v1/notification_preferences": { + "delete": { + "description": "Removes the authenticated user's explicit notification preference for a\ngiven `(type, channel)` combination, reverting that slot to the type's\ndefault channel set.\n\nThe `app_id` param scopes the deletion to a specific app's preference\nrow. Omit `app_id` to target the system-level (no-app) slot. Because\nthe two slots are stored independently, omitting `app_id` will not\nmatch a row that has one set, and vice versa.\n\nReturns `204 No Content` on success. Returns `404` if no preference\nexists for the given composite key.\n", + "operationId": "delete_api_v1_notification_preferences", + "parameters": [], + "responses": { + "204": { + "description": "Empty response body. A `204 No Content` status indicates the preference was deleted successfully." }, - { - "example": "string", - "in": "path", - "name": "private_service_id", - "required": true, - "schema": { - "type": "string" - } + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "App-scoped token required. Use a token scoped to the target app." + }, + "404": { + "description": "Notification preference not found" } - ], + }, + "summary": "Delete a notification preference", + "x-auth": [ + "publishable_key", + "bearer" + ] + }, + "get": { + "description": "Returns all explicit notification preferences belonging to the authenticated\nuser. Preferences are returned for every `(type, channel)` combination the\nuser has explicitly configured; slots that have not been overridden are not\nincluded and fall back to the type's defaults.\n\nThe recipient is derived from the authenticated viewer. You cannot retrieve\npreferences for any other user through this endpoint. All configured\npreferences — system-level and app-scoped — are returned together in the\n`data` array.\n", + "operationId": "get_api_v1_notification_preferences", + "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PrivateService" + "$ref": "#/components/schemas/NotificationPreferenceList" } } }, - "description": "Successful response" + "description": "An object with a `data` array containing all explicit notification preferences for the authenticated user." }, - "400": { - "description": "Bad request" + "401": { + "description": "Unauthorized" }, "403": { - "description": "Forbidden" - }, - "404": { - "description": "Not found" - }, - "503": { - "description": "Private service control is unavailable" + "description": "App-scoped token required. Use a token scoped to the target app." } }, - "summary": "Retrieve a private service", + "summary": "List notification preferences", "x-auth": [ "publishable_key", "bearer" ] - } - }, - "/api/v1/sandboxes": { - "post": { - "description": "Creates a new sandbox for the caller's app. A sandbox is an isolated environment\nthat can hold its own set of API keys, allowing you to test integrations without\naffecting production data.\n\nThe caller must authenticate with app-scoped credentials. Org-scoped viewers\nmay create sandboxes for their organization; developers and all-powerful\ncallers may create app-level or org-scoped sandboxes. If `org` is supplied the\nsandbox is scoped to that organization; otherwise it defaults to the\nauthenticated viewer's organization.\n\nRemote-eval sandboxes may set `purpose: \"eval\"` with `expires_at` at creation;\nTTL is the sole cleanup mechanism for those sandboxes. Returns the new sandbox\nwith the auto-issued publishable key — use the create key endpoint to issue\nsecret keys.\n", - "operationId": "post_api_v1_sandboxes", + }, + "put": { + "description": "Creates or replaces the authenticated user's notification preference for a\ngiven `(type, channel)` combination. This is an idempotent PUT: if no\npreference exists for the composite key, a new row is created; if one\nalready exists, its `enabled` flag is updated to the value you provide.\n\nThe recipient is derived from the authenticated viewer. You cannot set\npreferences for another user through this endpoint.\n\nPass `app_id` to scope the preference to a specific app's notifications —\nmost useful for the `app_*` notification type family. Omit `app_id` to\nconfigure the system-level (no-app) slot. System-level and app-scoped\npreferences are stored independently and do not overwrite each other.\n\nThe `in_app` channel is not configurable and will be rejected with a\nvalidation error if supplied.\n", + "operationId": "put_api_v1_notification_preferences", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "example": { - "expires_at": "2024-01-01T00:00:00Z", - "name": "Example Name", - "org": "string", - "purpose": "string", - "slug": "example-slug" + "app_id": "string", + "channel": "string", + "enabled": true, + "type": "string" }, "properties": { - "expires_at": { - "description": "Optional eval sandbox expiry in ISO 8601 format. Must be paired with `purpose: \"eval\"`.", - "example": "2024-01-01T00:00:00Z", - "format": "date-time", - "type": "string" - }, - "name": { - "description": "Human-readable display name for the sandbox.", - "example": "Example Name", - "type": "string" - }, - "org": { - "description": "Organization ID (`org_...`) to scope the sandbox to. Defaults to the authenticated viewer's organization when omitted.", + "app_id": { + "description": "App to scope this preference to. Omit to configure the system-level (no-app) slot. App-scoped and system-level preferences are stored separately and do not affect each other.", "example": "string", "type": "string" }, - "purpose": { - "description": "Optional sandbox purpose marker. Only `\"eval\"` is accepted, and it must be paired with `expires_at`.", + "channel": { + "description": "Delivery channel to configure (e.g., `\"email\"`, `\"sms\"`). The `in_app` channel is not configurable and will be rejected with a validation error.", "example": "string", "type": "string" }, - "slug": { - "description": "URL-safe identifier for the sandbox. Must be unique within the app.", - "example": "example-slug", + "enabled": { + "description": "Whether the specified channel should be enabled for this notification type and scope. Set to `false` to suppress delivery on this channel.", + "example": true, + "type": "boolean" + }, + "type": { + "description": "Notification type to configure. Use a builtin name (e.g., `\"app_info\"`, `\"billing_alert\"`) or a `\"custom:\"` identifier matching a NotificationType config registered in your app's bundle. Unknown type identifiers are rejected with a validation error.", + "example": "string", "type": "string" } }, "required": [ - "name", - "slug" + "type", + "channel", + "enabled" ], "type": "object" } @@ -39719,82 +41786,64 @@ "required": true }, "responses": { - "201": { + "200": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Sandbox" + "$ref": "#/components/schemas/NotificationPreference" } } }, - "description": "The newly created sandbox." + "description": "The created or updated notification preference reflecting the new `enabled` state." }, "401": { "description": "Unauthorized" }, "403": { - "description": "Forbidden" - }, - "404": { - "description": "Not found" + "description": "App-scoped token required. Use a token scoped to the target app.; Viewer has no recipient context (no associated user or developer account)." }, "422": { "description": "Validation failed" } }, - "summary": "Create a sandbox", + "summary": "Create or update a notification preference", "x-auth": [ "publishable_key", "bearer" ] } }, - "/api/v1/sandboxes/{sandbox}": { - "delete": { - "description": "Soft-deletes the specified sandbox. The sandbox is marked deleted and\nimmediately hidden from list/get queries; all of its active keys are revoked.\nHard deletion (child data cascade) is scheduled immediately via the background\nsandbox deletion worker — the same path used for developer-app soft-delete.\n\nThe caller must authenticate with app-scoped credentials and be allowed to\nmodify the sandbox. Returns 204 on success. If the sandbox is missing or\nalready deleted, a 404 is returned.\n", - "operationId": "delete_api_v1_sandboxes__sandbox", + "/api/v1/notifications": { + "get": { + "description": "Returns a cursor-paginated list of inbox notifications for the authenticated\nuser, ordered by creation time descending (newest first). All status groups\nare included by default; pass `status` to narrow results to a specific group.\n\nEach notification's `rendered` field contains type-specific display data\nresolved at request time. Notifications whose type is no longer registered\nin the platform are rendered with `kind: \"unknown\"` rather than being omitted.\n\nPagination is forward-only: supply `after_cursor` from a previous response to\nfetch the next (older) page. The `before_cursor` field is always `null` for\nthis endpoint. Requires an app-scoped token.\n", + "operationId": "get_api_v1_notifications", "parameters": [ { - "description": "Sandbox ID (`dsb_...`) of the sandbox to delete.", + "description": "Filter by notification status. One of `\"all\"`, `\"active\"`, `\"unread\"`, `\"read\"`, or `\"archived\"`. Defaults to `\"all\"` when omitted.", "example": "string", - "in": "path", - "name": "sandbox", - "required": true, + "in": "query", + "name": "status", + "required": false, "schema": { "type": "string" } - } - ], - "responses": { - "204": { - "description": "Empty response with HTTP 204 status on successful deletion." }, - "401": { - "description": "Unauthorized" - }, - "403": { - "description": "Forbidden" + { + "description": "Maximum number of notifications to return per page. Defaults to 20; maximum is 100.", + "example": 1, + "in": "query", + "name": "limit", + "required": false, + "schema": { + "type": "integer" + } }, - "404": { - "description": "Sandbox not found" - } - }, - "summary": "Delete a sandbox", - "x-auth": [ - "publishable_key", - "bearer" - ] - }, - "get": { - "description": "Returns the sandbox identified by `sandbox` that belongs to the caller's app.\nThe response includes the sandbox's associated keys (without full secret key\nvalues — full keys are only available at creation time).\n\nThe caller must authenticate with app-scoped credentials. Org members may view\ntheir org's sandboxes; developers and all-powerful callers may view app-level\nand org-scoped sandboxes in their app. Returns 404 if the sandbox does not\nexist or is not visible to the caller.\n", - "operationId": "get_api_v1_sandboxes__sandbox", - "parameters": [ { - "description": "Sandbox ID (`dsb_...`) to retrieve.", + "description": "Opaque pagination cursor from a previous response's `after_cursor` field. Omit to fetch the most recent notifications.", "example": "string", - "in": "path", - "name": "sandbox", - "required": true, + "in": "query", + "name": "after_cursor", + "required": false, "schema": { "type": "string" } @@ -39805,281 +41854,205 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Sandbox" - } - } - }, - "description": "The requested sandbox." - }, - "401": { - "description": "Unauthorized" - }, - "403": { - "description": "Forbidden" - }, - "404": { - "description": "Sandbox not found" - } - }, - "summary": "Retrieve a sandbox", - "x-auth": [ - "publishable_key", - "bearer" - ] - } - }, - "/api/v1/sandboxes/{sandbox}/keys": { - "post": { - "description": "Issues a new API key for the specified sandbox. Keys can be either\n`\"publishable\"` (safe to embed in client-side code) or `\"secret\"` (server-side\nonly). The full key value is returned once in the `full_key` field of this\nresponse and is never retrievable again — store it securely immediately.\n\nThe caller must authenticate with app-scoped credentials and be able to\nmodify the sandbox (org members for org sandboxes; developers / all-powerful\nfor app-level). If the sandbox does not belong to the caller's app or is not\nvisible, a 404 is returned. Multiple active keys per sandbox are supported;\nrevoke individual keys with the revoke key endpoint.\n", - "operationId": "post_api_v1_sandboxes__sandbox_keys", - "parameters": [ - { - "description": "Sandbox ID (`dsb_...`). The key is created for this sandbox.", - "example": "string", - "in": "path", - "name": "sandbox", - "required": true, - "schema": { - "type": "string" - } - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "example": { - "type": "string" - }, - "properties": { - "type": { - "description": "Key type. One of `\"publishable\"` or `\"secret\"`. Defaults to `\"publishable\"`.", - "example": "string", - "type": "string" - } - }, - "type": "object" - } - } - }, - "required": true - }, - "responses": { - "201": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SandboxKey" + "description": "Cursor-paginated list of notifications for the authenticated user.", + "example": { + "after_cursor": "string", + "before_cursor": "string", + "data": [ + { + "archived_at": "2024-01-01T00:00:00Z", + "created_at": "2024-01-01T00:00:00Z", + "id": "ntf_0aBcDeFgHiJkLmNoPqRsTu", + "read_at": "2024-01-01T00:00:00Z", + "rendered": {}, + "status": "unread", + "type": "app_info" + } + ], + "has_more": true + }, + "properties": { + "after_cursor": { + "description": "Opaque cursor to pass as `after_cursor` on the next request to fetch older notifications. `null` when this is the last page.", + "example": "string", + "type": "string" + }, + "before_cursor": { + "description": "Always `null` — inbox pagination is forward-only and does not support fetching newer pages via cursor.", + "example": "string", + "type": "string" + }, + "data": { + "description": "Array of notification objects for the current page, ordered newest first.", + "example": [ + { + "archived_at": "2024-01-01T00:00:00Z", + "created_at": "2024-01-01T00:00:00Z", + "id": "ntf_0aBcDeFgHiJkLmNoPqRsTu", + "read_at": "2024-01-01T00:00:00Z", + "rendered": {}, + "status": "unread", + "type": "app_info" + } + ], + "items": { + "description": "An inbox notification delivered to a recipient user. Includes type-specific render data resolved at request time.", + "example": { + "archived_at": "2024-01-01T00:00:00Z", + "created_at": "2024-01-01T00:00:00Z", + "id": "ntf_0aBcDeFgHiJkLmNoPqRsTu", + "read_at": "2024-01-01T00:00:00Z", + "rendered": {}, + "status": "unread", + "type": "app_info" + }, + "properties": { + "archived_at": { + "description": "When the recipient archived this notification. `null` if the notification has not been archived.", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "type": "string" + }, + "created_at": { + "description": "When the notification was sent (ISO 8601).", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "type": "string" + }, + "id": { + "description": "Notification ID (`ntf_...`).", + "example": "ntf_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "read_at": { + "description": "When the recipient marked this notification read. `null` if the notification has not been read.", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "type": "string" + }, + "rendered": { + "description": "Type-specific render spec resolved at request time. All types include `title`, `kind`, and `actions`; custom types may add their own keys. Notifications whose type is no longer registered render with `kind: \"unknown\"`.", + "example": {}, + "type": "object" + }, + "status": { + "description": "Current read state of the notification. One of `\"unread\"`, `\"read\"`, or `\"archived\"`.", + "example": "unread", + "type": "string" + }, + "type": { + "description": "Notification type slug, e.g. `\"app_info\"` for a built-in type or `\"custom:deploy_complete\"` for a custom type.", + "example": "app_info", + "type": "string" + } + }, + "required": [ + "id", + "type", + "status", + "rendered", + "created_at" + ], + "type": "object" + }, + "type": "array" + }, + "has_more": { + "description": "`true` if additional (older) notifications exist beyond this page; `false` if this is the last page.", + "example": true, + "type": "boolean" + } + }, + "required": [ + "data", + "has_more" + ], + "type": "object" } } }, - "description": "The newly created sandbox key, including the one-time `full_key` value." + "description": "Successful response" + }, + "400": { + "description": "Bad request; Invalid cursor" }, "401": { "description": "Unauthorized" }, "403": { - "description": "Forbidden" - }, - "404": { - "description": "Sandbox not found" - }, - "422": { - "description": "Validation failed" + "description": "App-scoped token required. Use a token scoped to the target app." } }, - "summary": "Create a sandbox key", + "summary": "List a user's notifications", "x-auth": [ "publishable_key", "bearer" ] } }, - "/api/v1/slack_channel_bindings": { - "get": { - "description": "Returns a page of Slack channel bindings visible to the authenticated user.\nResults can be filtered by integration, team, agent, or organization. Omit all\nfilter params to retrieve every binding the caller can see.\n\nPagination is page-based. Pass `page` and `per_page` to navigate large result\nsets. `page` must be a positive integer; `per_page` must be between 1 and 100.\nInvalid values return 400.\n", - "operationId": "get_api_v1_slack_channel_bindings", - "parameters": [ - { - "description": "Return only bindings whose Slack integration matches one of these integration IDs. Omit to return bindings across all integrations.", - "example": [ - "string" - ], - "in": "query", - "name": "integration", - "required": false, - "schema": { - "items": { - "type": "string" - }, - "type": "array" - } - }, - { - "description": "Return only bindings bound to one of these team IDs. Omit to return bindings for all teams.", - "example": [ - "string" - ], - "in": "query", - "name": "team", - "required": false, - "schema": { - "items": { - "type": "string" - }, - "type": "array" - } - }, - { - "description": "Return only bindings that have at least one of these agent user IDs attached. Omit to return bindings regardless of agent attachment.", - "example": [ - "string" - ], - "in": "query", - "name": "agent", - "required": false, - "schema": { - "items": { - "type": "string" - }, - "type": "array" - } - }, - { - "description": "Return only bindings that belong to one of these organization IDs. Omit to return bindings across all organizations visible to the caller.", - "example": [ - "string" - ], - "in": "query", - "name": "org", - "required": false, - "schema": { - "items": { - "type": "string" - }, - "type": "array" - } - }, - { - "description": "Page number to retrieve, 1-indexed. Defaults to 1. Must be a positive integer.", - "example": 1, - "in": "query", - "name": "page", - "required": false, - "schema": { - "type": "integer" - } - }, - { - "description": "Number of bindings to return per page. Defaults to 25; maximum is 100.", - "example": 1, - "in": "query", - "name": "per_page", - "required": false, - "schema": { - "type": "integer" - } - } - ], + "/api/v1/notifications/read_all": { + "post": { + "description": "Marks every `\"unread\"` notification belonging to the authenticated user as\n`\"read\"` in a single operation. Notifications that are already `\"read\"` or\n`\"archived\"` are not affected.\n\nThis call is safe to retry — if there are no unread notifications, it\nsucceeds without error. Requires an app-scoped token. Returns 204 No Content\non success.\n", + "operationId": "post_api_v1_notifications_read_all", + "parameters": [], "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SlackChannelBindingListResponse" - } - } - }, - "description": "Paginated list of Slack channel bindings visible to the caller." - }, - "400": { - "description": "Bad request" + "204": { + "description": "No content" }, "401": { "description": "Unauthorized" }, "403": { - "description": "Forbidden" + "description": "App-scoped token required. Use a token scoped to the target app." } }, - "summary": "List Slack channel bindings", + "summary": "Mark all notifications as read", "x-auth": [ "publishable_key", "bearer" ] - }, + } + }, + "/api/v1/notifications/send": { "post": { - "description": "Creates a new binding between a Slack channel and a team, or updates the\nexisting binding if one already exists for the given channel. The caller also\nsupplies a list of agents to attach to the binding and enroll as members of the\ndestination team.\n\nThe caller must have team-manage rights on the destination team (and on the\ncurrently bound team if the channel is being re-pointed). Returns 403 if\npermission is insufficient. All write steps are idempotent, so retrying after\na partial failure is safe.\n\nOn success the REST endpoint returns 201 Created. The script binding\n(`slack.channel_bindings.upsert`) returns the full binding object including the\nattached agents.\n", - "operationId": "post_api_v1_slack_channel_bindings", + "description": "Delivers a custom-typed notification to one of the calling app's users.\nApps define notification types by declaring `NotificationType` config objects\nin their bundle (one per `lookup_key`). Supply the type as\n`\"custom:\"` and provide a `data` map that is merged with\nplatform-provided context to render the notification's display fields.\n\nOnly app-scoped tokens may call this endpoint — user tokens are rejected with\n403. The app scope is stamped onto the notification automatically; an app\ncannot target recipients outside its tenant. Built-in platform types such as\n`\"app_info\"` and `\"billing_alert\"` are not accepted here.\n\nPass `idempotency_key` to deduplicate sends. If you call this endpoint twice\nwith the same `idempotency_key` for the same recipient, the second call\nreturns the original notification without creating a duplicate. The key is\nscoped to the calling app, so the same raw key used by different apps cannot\ncollide.\n", + "operationId": "post_api_v1_notifications_send", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "example": { - "agent_user_ids": [ - "string" - ], - "allow_bot_conversations": true, - "channel_id": "string", - "customer_label": "string", - "is_ext_shared_cached": true, - "is_private_cached": true, - "slack_team_id": "string", - "team_id": "string" + "data": {}, + "idempotency_key": "string", + "type": "string", + "user": "string" }, "properties": { - "agent_user_ids": { - "description": "List of agent user IDs to attach to the binding and enroll as members of the destination team. Pass an empty array to bind the channel without attaching any agents.", - "example": [ - "string" - ], - "items": { - "type": "string" - }, - "type": "array" - }, - "allow_bot_conversations": { - "description": "Opt this channel into sustained bot-to-bot conversation: the reply loop brake is disabled for its mirror thread. Set when the counterparty is a known bot the agent should keep answering. Omitting the parameter leaves the stored value unchanged.", - "example": true, - "type": "boolean" - }, - "channel_id": { - "description": "Slack channel ID to bind (e.g. `C01234ABCDE`). Acts as the natural key of the binding within the workspace.", - "example": "string", - "type": "string" + "data": { + "description": "Arbitrary key-value payload merged with platform-provided context (recipient, app, org, brand) when rendering the notification's display fields. Defaults to an empty object when omitted.", + "example": {}, + "type": "object" }, - "customer_label": { - "description": "Human-readable label for the customer associated with this channel. Stored in the binding's config. `null` if omitted.", + "idempotency_key": { + "description": "Optional deduplication key. A second call with the same `idempotency_key` for the same recipient returns the originally-created notification without inserting a new record. Scoped per calling app.", "example": "string", "type": "string" }, - "is_ext_shared_cached": { - "description": "Cached value of Slack's `is_ext_shared` flag for the channel. When provided, this value is persisted on the binding to avoid repeated Slack API lookups. `null` if omitted.", - "example": true, - "type": "boolean" - }, - "is_private_cached": { - "description": "Cached value of Slack's `is_private` flag for the channel. When provided, this value is persisted on the binding to avoid repeated Slack API lookups. Private channels are member-managed. `null` if omitted.", - "example": true, - "type": "boolean" - }, - "slack_team_id": { - "description": "Slack workspace team ID that the channel belongs to (e.g. `T01234ABCDE`). Identifies which Slack integration to use.", + "type": { + "description": "Custom notification type identifier in the form `\"custom:\"`, where `` matches a `NotificationType` config declared in the calling app's bundle.", "example": "string", "type": "string" }, - "team_id": { - "description": "ID of the team to bind the Slack channel to. The caller must have team-manage rights on this team.", + "user": { + "description": "Recipient user ID (`usr_...`). Must be a member of the calling app's tenant.", "example": "string", "type": "string" } }, "required": [ - "slack_team_id", - "channel_id", - "team_id", - "agent_user_ids" + "type", + "user" ], "type": "object" } @@ -40092,11 +42065,11 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SlackChannelBinding" + "$ref": "#/components/schemas/Notification" } } }, - "description": "The created or updated Slack channel binding, including the full list of currently attached agents." + "description": "The created notification, or the existing notification when deduplicated by `idempotency_key`." }, "400": { "description": "Bad request" @@ -40105,148 +42078,76 @@ "description": "Unauthorized" }, "403": { - "description": "Forbidden; The Slack integration referenced by this binding is not visible to the caller" + "description": "App-scoped token required. Use a token scoped to the target app.; Forbidden" }, "404": { - "description": "Agent not found; Team not found" - }, - "409": { - "description": "Channel already has a resident agent" + "description": "User not found" }, "422": { - "description": "Invalid parameters; Binding org_id does not match the integration's org_id" + "description": "Invalid parameters; No NotificationType config matched this `custom:` in the calling app's bundle." } }, - "summary": "Create or update a Slack channel binding", + "summary": "Send a custom notification to a user", "x-auth": [ "publishable_key", "bearer" ] } }, - "/api/v1/slack_channel_bindings/provision": { - "post": { - "description": "Opens a Slack Connect channel with a new customer — creating one and sending\nthe invite, or adopting a shared channel you already have — and records who is\nadding whom so the addition can finish once the customer accepts.\n\nThe returned binding is **pending**: nothing mirrors, and no per-customer Team,\nagent, or solution instance exists yet. Acceptance is asynchronous and may\nnever come. When it does, the addition completes in the background under the\nidentity of the admin who called this endpoint, re-checked live at that moment.\nA caller who has since lost their admin role does not get a substitute — the\naddition is refused and a human re-adds the customer.\n\nThe caller must be an admin of the Slack integration's own organization. This\nis the same authority the completion demands, checked here so a customer is\nnever invited into a channel whose addition can never finish.\n\nDeliberately not exposed as a script binding: this sends mail to a person\noutside the org, so it stays a vendor-admin HTTP surface.\n", - "operationId": "post_api_v1_slack_channel_bindings_provision", + "/api/v1/notifications/unread_count": { + "get": { + "description": "Returns the total number of `\"unread\"` notifications for the authenticated\nuser. Useful for displaying a badge or indicator in your UI without\nfetching the full notification list.\n\nNotifications with `\"read\"` or `\"archived\"` status are not included in the\ncount. Requires an app-scoped token.\n", + "operationId": "get_api_v1_notifications_unread_count", "parameters": [], - "requestBody": { - "content": { - "application/json": { - "schema": { - "example": { - "channel_name": "Example Name", - "customer_email": "user@example.com", - "customer_key": "string", - "customer_label": "string", - "existing_channel_id": "string", - "inputs": {}, - "slack_team_id": "string", - "template_config_id": "string" - }, - "properties": { - "channel_name": { - "description": "Name for a Slack channel to create for this customer. Required unless `existing_channel_id` is given. The channel is created private.", - "example": "Example Name", - "type": "string" - }, - "customer_email": { - "description": "Address the Slack Connect invite is sent to. Required when creating a channel; optional when adopting one the customer is already in. Whoever accepts becomes the verified counterparty.", - "example": "user@example.com", - "type": "string" - }, - "customer_key": { - "description": "The vendor's own primary key for this customer (`customer_id` / `account_id` / `tenant_id`). The per-customer agent's data access is locked to it. Immutable once the customer is added: re-targeting means offboarding and re-provisioning.", - "example": "string", - "type": "string" - }, - "customer_label": { - "description": "Human-readable name for the customer (e.g. `Acme, Inc.`). Used for the vendor's own dashboards and as the per-customer Team's name. Not an identity or an access control input.", - "example": "string", - "type": "string" - }, - "existing_channel_id": { - "description": "Adopt this already-shared Slack Connect channel (e.g. `C01234ABCDE`) instead of creating one. Mutually exclusive with `channel_name`.", - "example": "string", - "type": "string" - }, - "inputs": { - "description": "String-keyed values the per-customer solution instance is stamped with. Defaults to an empty map.", - "example": {}, - "type": "object" - }, - "slack_team_id": { - "description": "Slack workspace team ID of the vendor's own Slack installation (e.g. `T01234ABCDE`). The customer's workspace is not known yet — it resolves from whoever accepts.", - "example": "string", - "type": "string" - }, - "template_config_id": { - "description": "Config ID (`cfg_…`) of the org-installed Solution the per-customer instance is stamped from. Must be the organization's own installed copy, not the catalog original — instances stamped from a different config do not appear in the vendor's customer fleet.", - "example": "string", - "type": "string" - } - }, - "required": [ - "slack_team_id", - "customer_label", - "customer_key", - "template_config_id" - ], - "type": "object" - } - } - }, - "required": true - }, "responses": { "200": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SlackChannelBinding" + "description": "Object containing the count of unread notifications for the authenticated user.", + "example": { + "count": 1 + }, + "properties": { + "count": { + "description": "Total number of notifications with `\"unread\"` status belonging to the authenticated user.", + "example": 1, + "type": "integer" + } + }, + "required": [ + "count" + ], + "type": "object" } } }, - "description": "The pending binding for the customer's channel. `disclosure_state` is `pending` until the customer accepts, and `scope_key` is null until the addition finishes." - }, - "400": { - "description": "Bad request" + "description": "Successful response" }, "401": { "description": "Unauthorized" }, "403": { - "description": "Forbidden; Admin role required for this operation; The Slack integration referenced by this binding is not visible to the caller" - }, - "409": { - "description": "Conflict" - }, - "422": { - "description": "Invalid parameters" - }, - "500": { - "description": "Internal server error" - }, - "502": { - "description": "Provider returned an error" + "description": "App-scoped token required. Use a token scoped to the target app." } }, - "summary": "Start adding a customer over Slack Connect", + "summary": "Get the unread notification count", "x-auth": [ "publishable_key", "bearer" ] } }, - "/api/v1/slack_channel_bindings/{channel}": { - "delete": { - "description": "Removes the binding between a Slack channel and its associated team. The\nchannel is identified by its Slack channel ID together with the `slack_team_id`\nthat scopes it to a specific Slack workspace. Removing the binding does not\ndelete the bound team or any conversation threads scoped to it; decommission\nthose resources separately if required.\n\nThe caller must have team-manage rights on the team the channel is currently\nbound to. Returning 403 indicates insufficient permission; returning 404\nindicates the binding does not exist or is not visible to the caller.\n\nThe REST endpoint returns 204 No Content on success. The script binding\n(`slack.channel_bindings.delete`) returns a confirmation object so script\ncallers can verify success without an additional fetch. Both paths are\nidempotent — retrying after a partial failure is safe.\n", - "operationId": "delete_api_v1_slack_channel_bindings__channel", + "/api/v1/notifications/{notification}/archive": { + "post": { + "description": "Moves a notification to `\"archived\"` status regardless of whether it is\ncurrently `\"unread\"` or `\"read\"`. Archived notifications are excluded from\nthe default inbox view but remain retrievable by passing `status: \"archived\"`\nto the list endpoint.\n\nThe authenticated user must own the notification. Passing a notification ID\nthat belongs to a different user returns a 404. If the notification is\nalready archived this call succeeds without error (idempotent).\n\nRequires an app-scoped token. Returns 204 No Content on success.\n", + "operationId": "post_api_v1_notifications__notification_archive", "parameters": [ { - "description": "Slack channel ID of the binding to delete (e.g. `C01234ABCDE`).", + "description": "Notification ID (`ntf_...`) to archive. Must belong to the authenticated user.", "example": "string", "in": "path", - "name": "channel", + "name": "notification", "required": true, "schema": { "type": "string" @@ -40254,30 +42155,233 @@ } ], "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "description": "Deletion confirmation returned by the script binding. The REST endpoint returns 204 No Content with no body.", + "204": { + "description": "No content" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "App-scoped token required. Use a token scoped to the target app." + }, + "404": { + "description": "Notification not found" + } + }, + "summary": "Archive a notification", + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/notifications/{notification}/read": { + "post": { + "description": "Transitions a notification from `\"unread\"` to `\"read\"` status. If the\nnotification is already `\"read\"` or `\"archived\"`, the call succeeds without\nchanging its status (idempotent).\n\nThe authenticated user must own the notification. Passing a notification ID\nthat belongs to a different user returns a 404. Requires an app-scoped token.\nReturns 204 No Content on success.\n", + "operationId": "post_api_v1_notifications__notification_read", + "parameters": [ + { + "description": "Notification ID (`ntf_...`) to mark as read. Must belong to the authenticated user.", + "example": "string", + "in": "path", + "name": "notification", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "No content" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "App-scoped token required. Use a token scoped to the target app." + }, + "404": { + "description": "Notification not found" + } + }, + "summary": "Mark a notification as read", + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/notifications/{notification}/unarchive": { + "post": { + "description": "Restores an `\"archived\"` notification to its previous active status:\n`\"read\"` if the notification had been read before archiving, or `\"unread\"`\notherwise. The notification will appear again in the default inbox view.\n\nThe authenticated user must own the notification. Passing a notification ID\nthat belongs to a different user returns a 404. If the notification is not\ncurrently archived this call succeeds without changing its status (idempotent).\nRequires an app-scoped token. Returns 204 No Content on success.\n", + "operationId": "post_api_v1_notifications__notification_unarchive", + "parameters": [ + { + "description": "Notification ID (`ntf_...`) to unarchive. Must belong to the authenticated user.", + "example": "string", + "in": "path", + "name": "notification", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "No content" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "App-scoped token required. Use a token scoped to the target app." + }, + "404": { + "description": "Notification not found" + } + }, + "summary": "Unarchive a notification", + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/orgs": { + "get": { + "description": "Returns a paginated list of organizations within the authenticated app scope,\noptionally filtered by a free-text search term matched against name, slug, and\ndomain (case-insensitive). Results are ordered by relevance when a search term\nis provided, and by creation time descending otherwise.\n\nThe response includes only public-facing organization fields: ID, name, domain,\nand logo. Use the developer-scoped org endpoints to access full organization\nrecords.\n\nPagination is offset-based. Pass `page` and `page_size` to navigate through\nresults. The `has_next` and `has_prev` fields indicate whether adjacent pages\nexist.\n", + "operationId": "get_api_v1_orgs", + "parameters": [ + { + "description": "Free-text search term matched against organization name, slug, and domain (case-insensitive). Omit to return all organizations in the app.", + "example": "string", + "in": "query", + "name": "search", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Page number to retrieve, starting at `1`. Defaults to `1` when omitted.", + "example": 1, + "in": "query", + "name": "page", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "description": "Number of organizations to return per page. Defaults to `25`; maximum is `100`.", + "example": 1, + "in": "query", + "name": "page_size", + "required": false, + "schema": { + "type": "integer" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "description": "Paginated list of organizations matching the query.", "example": { - "channel": "string", - "deleted": true + "data": [ + { + "domain": "acme.com", + "id": "org_0aBcDeFgHiJkLmNoPqRsTu", + "name": "Example Name" + } + ], + "has_next": true, + "has_prev": true, + "page": 1, + "page_size": 1, + "total_entries": 1, + "total_pages": 1 }, "properties": { - "channel": { - "description": "Slack channel ID of the binding that was deleted.", - "example": "string", - "type": "string" + "data": { + "description": "Array of organization objects for the current page.", + "example": [ + { + "domain": "acme.com", + "id": "org_0aBcDeFgHiJkLmNoPqRsTu", + "name": "Example Name" + } + ], + "items": { + "description": "A minimal organization object returned on authenticated endpoints. Exposes only the fields safe for any authenticated user: identity, display name, primary domain, and logo.", + "example": { + "domain": "acme.com", + "id": "org_0aBcDeFgHiJkLmNoPqRsTu", + "name": "Example Name" + }, + "properties": { + "domain": { + "description": "Primary domain associated with the organization, e.g. `\"acme.com\"`.", + "example": "acme.com", + "type": "string" + }, + "id": { + "description": "Organization ID (`org_...`).", + "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "type": "string" + }, + "name": { + "description": "Display name of the organization.", + "example": "Example Name", + "type": "string" + } + }, + "required": [ + "id", + "name", + "domain" + ], + "type": "object" + }, + "type": "array" }, - "deleted": { - "description": "Always `true` when the binding was successfully removed.", + "has_next": { + "description": "`true` when a subsequent page exists; `false` on the last page.", "example": true, "type": "boolean" + }, + "has_prev": { + "description": "`true` when a previous page exists; `false` on the first page.", + "example": true, + "type": "boolean" + }, + "page": { + "description": "The current page number returned.", + "example": 1, + "type": "integer" + }, + "page_size": { + "description": "The number of results per page used for this response.", + "example": 1, + "type": "integer" + }, + "total_entries": { + "description": "Total number of organizations matching the query across all pages.", + "example": 1, + "type": "integer" + }, + "total_pages": { + "description": "Total number of pages for the current query and page size.", + "example": 1, + "type": "integer" } }, "required": [ - "deleted", - "channel" + "data" ], "type": "object" } @@ -40285,47 +42389,38 @@ }, "description": "Successful response" }, - "400": { - "description": "Bad request" - }, "401": { "description": "Unauthorized" }, "403": { - "description": "Forbidden; The Slack integration referenced by this binding is not visible to the caller" - }, - "404": { - "description": "Slack channel binding not found" - }, - "422": { - "description": "Invalid parameters" + "description": "App-scoped token required. Use a token scoped to the target app." } }, - "summary": "Delete a Slack channel binding", + "summary": "Search organizations", "x-auth": [ "publishable_key", "bearer" ] - }, + } + }, + "/api/v1/private_service_definitions/{app_id}/{private_service_id}": { "get": { - "description": "Returns the Slack channel binding identified by a Slack channel ID and workspace\nteam ID pair. Use this endpoint to look up the team and agents currently bound\nto a specific Slack channel.\n\nThe `channel` path parameter is the Slack channel ID; `slack_team_id` identifies\nthe Slack workspace the channel belongs to, disambiguating channels with the same\nID across workspaces. Both parameters are required. Returns 404 if no binding\nexists for the given pair or the associated Slack integration is not visible to\nthe caller.\n", - "operationId": "get_api_v1_slack_channel_bindings__channel", + "description": "Returns the canonical callable definition authorized by an enrollment token.", + "operationId": "get_api_v1_private_service_definitions__app_id__private_service_id", "parameters": [ { - "description": "Slack channel ID of the binding to retrieve (e.g. `C01234ABCDE`).", "example": "string", "in": "path", - "name": "channel", + "name": "app_id", "required": true, "schema": { "type": "string" } }, { - "description": "Slack workspace team ID that the channel belongs to (e.g. `T01234ABCDE`). Used together with `channel` to uniquely identify the binding.", "example": "string", - "in": "query", - "name": "slack_team_id", + "in": "path", + "name": "private_service_id", "required": true, "schema": { "type": "string" @@ -40337,73 +42432,117 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SlackChannelBinding" + "format": "binary", + "type": "string" } } }, - "description": "The Slack channel binding for the given channel and workspace." - }, - "400": { - "description": "Bad request" + "description": "Raw content" }, "401": { - "description": "Unauthorized" - }, - "403": { - "description": "The Slack integration referenced by this binding is not visible to the caller" + "description": "Invalid enrollment token" }, "404": { - "description": "Slack channel binding not found" + "description": "Not found" }, - "422": { - "description": "Invalid parameters" + "503": { + "description": "Private service control is unavailable" } }, - "summary": "Retrieve a Slack channel binding", - "x-auth": [ - "publishable_key", - "bearer" - ] + "summary": "Download an enrolled private service definition" } }, - "/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", - "operationId": "post_api_v1_slack_channel_bindings__channel_deposit_thread", + "/api/v1/private_service_enrollments": { + "get": { + "operationId": "get_api_v1_private_service_enrollments", "parameters": [ { - "description": "Slack channel ID whose binding is being configured (e.g. `C01234ABCDE`).", + "description": "Organization ID or slug. Required for developer and server callers.", "example": "string", - "in": "path", - "name": "channel", - "required": true, + "in": "query", + "name": "org", + "required": false, "schema": { "type": "string" } + }, + { + "description": "Page number. Defaults to 1.", + "example": 1, + "in": "query", + "name": "page", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "description": "Results per page. Defaults to 25; maximum is 100.", + "example": 1, + "in": "query", + "name": "page_size", + "required": false, + "schema": { + "type": "integer" + } } ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PrivateServiceEnrollmentPage" + } + } + }, + "description": "Successful response" + }, + "400": { + "description": "Bad request" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not found" + }, + "503": { + "description": "Private service control is unavailable" + } + }, + "summary": "List private service enrollments", + "x-auth": [ + "publishable_key", + "bearer" + ] + }, + "post": { + "description": "Creates or safely replaces an unreserved one-time connector enrollment token.", + "operationId": "post_api_v1_private_service_enrollments", + "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "example": { - "slack_team_id": "string", - "thread_id": "string" + "org": "string", + "private_service": "string" }, "properties": { - "slack_team_id": { - "description": "Slack workspace team ID that the channel belongs to (e.g. `T01234ABCDE`). Identifies which Slack integration to use.", + "org": { + "description": "Organization ID or slug. Required for developer and server callers.", "example": "string", "type": "string" }, - "thread_id": { - "description": "Staging thread ID (primary key, `thr_…`) deposits should flow into. Pass `null` to turn the pipe off.", + "private_service": { + "description": "Private service ID (`pvs_...`).", "example": "string", "type": "string" } }, "required": [ - "slack_team_id" + "private_service" ], "type": "object" } @@ -40416,124 +42555,58 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SlackChannelBinding" + "$ref": "#/components/schemas/CreatedPrivateServiceEnrollment" } } }, - "description": "The binding with the updated deposit config." + "description": "Successful response" }, "400": { "description": "Bad request" }, - "401": { - "description": "Unauthorized" - }, "403": { - "description": "Forbidden; The Slack integration referenced by this binding is not visible to the caller" + "description": "Forbidden" }, "404": { "description": "Not found" }, - "422": { - "description": "Invalid parameters" + "409": { + "description": "Conflict" + }, + "503": { + "description": "Private service control is unavailable" } }, - "summary": "Point a Slack channel's deposit pipe at a staging thread, or turn it off", + "summary": "Create a private service enrollment", "x-auth": [ "publishable_key", "bearer" ] } }, - "/api/v1/solution_categories": { + "/api/v1/private_service_enrollments/{private_service_enrollment_id}": { "get": { - "description": "Returns a paginated list of solution category definitions visible to the authenticated caller.\nUse filters to narrow results by key, parent key, lookup key, or virtual path prefix.\n\nResults are scoped to categories accessible under the caller's viewer context. Pass `app` to\nrestrict the listing to categories associated with a specific app scope. Omit `owners` to\nreturn categories from all ownership scopes (`\"system\"` and `\"org\"`) that the caller can see.\n\nPagination is page-based. Use `page` and `page_size` to navigate large result sets. The\nresponse includes `total_entries`, `total_pages`, `has_next`, and `has_prev` to support\npagination controls. `total_entries` reflects the count after key deduplication.\n", - "operationId": "get_api_v1_solution_categories", + "operationId": "get_api_v1_private_service_enrollments__private_service_enrollment_id", "parameters": [ { - "description": "Page number to retrieve, 1-indexed. Defaults to `1`.", - "example": 1, - "in": "query", - "name": "page", - "required": false, - "schema": { - "type": "integer" - } - }, - { - "description": "Number of solution categories to return per page. Defaults to `25`.", - "example": 1, - "in": "query", - "name": "page_size", - "required": false, - "schema": { - "type": "integer" - } - }, - { - "description": "Return only categories whose key exactly matches one of the provided values.", - "example": [ - "string" - ], - "in": "query", - "name": "keys", - "required": false, - "schema": { - "items": { - "type": "string" - }, - "type": "array" - } - }, - { - "description": "Return only categories whose parent key matches one of the provided values. Pass an empty array to return root-level categories.", - "example": [ - "string" - ], - "in": "query", - "name": "parent_keys", - "required": false, - "schema": { - "items": { - "type": "string" - }, - "type": "array" - } - }, - { - "description": "Return only the category whose `lookup_key` exactly matches this value.", + "description": "Organization ID or slug. Required for developer and server callers.", "example": "string", "in": "query", - "name": "lookup_key", + "name": "org", "required": false, "schema": { "type": "string" } }, { - "description": "Return only categories whose `virtual_path` starts with this prefix.", + "description": "Canonical certificate-bound service identity.", "example": "string", - "in": "query", - "name": "path_prefix", - "required": false, + "in": "path", + "name": "private_service_enrollment_id", + "required": true, "schema": { "type": "string" } - }, - { - "description": "Restrict results to categories owned by the specified scopes. Accepted values are `\"system\"` and `\"org\"`. Omit to include all ownership scopes visible to the caller.", - "example": [ - "string" - ], - "in": "query", - "name": "owners", - "required": false, - "schema": { - "items": { - "type": "string" - }, - "type": "array" - } } ], "responses": { @@ -40541,59 +42614,64 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SolutionCategoryListResponse" + "$ref": "#/components/schemas/PrivateServiceEnrollment" } } }, - "description": "Paginated list of solution category summaries matching the applied filters." + "description": "Successful response" }, - "401": { - "description": "Unauthorized" + "400": { + "description": "Bad request" }, "403": { - "description": "Forbidden — app scope required" + "description": "Forbidden" + }, + "404": { + "description": "Not found" + }, + "503": { + "description": "Private service control is unavailable" } }, - "summary": "List solution categories", + "summary": "Retrieve a private service enrollment", "x-auth": [ "publishable_key", "bearer" ] } }, - "/api/v1/solution_instances": { + "/api/v1/private_services": { "get": { - "description": "Returns a forward cursor-paginated page of customer instances stamped from one\nsolution template. Results are restricted to the caller's organization; an\napp-wide viewer without an organization scope is forbidden.\n\nPass `after_cursor` from a response with `has_more: true` to retrieve the next\npage. Each row includes the materialized agent, pinned template version, and\nlocal-edit count computed by the solution-instance read path.\n", - "operationId": "get_api_v1_solution_instances", + "operationId": "get_api_v1_private_services", "parameters": [ { - "description": "ID of the installed solution template whose customer instances should be listed.", + "description": "Organization ID or slug. Required for developer and server callers.", "example": "string", "in": "query", - "name": "solution_template_config_id", - "required": true, + "name": "org", + "required": false, "schema": { "type": "string" } }, { - "description": "Maximum number of instances to return. Defaults to 50; maximum is 100.", + "description": "Page number. Defaults to 1.", "example": 1, "in": "query", - "name": "limit", + "name": "page", "required": false, "schema": { "type": "integer" } }, { - "description": "Opaque cursor returned by the preceding page. Omit to retrieve the first page.", - "example": "string", + "description": "Results per page. Defaults to 25; maximum is 100.", + "example": 1, "in": "query", - "name": "after_cursor", + "name": "page_size", "required": false, "schema": { - "type": "string" + "type": "integer" } } ], @@ -40602,103 +42680,338 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SolutionInstanceListResponse" + "$ref": "#/components/schemas/PrivateServicePage" } } }, - "description": "Cursor-paginated customer solution instances visible to the caller." + "description": "Successful response" }, "400": { - "description": "Bad request; Invalid cursor" + "description": "Bad request" }, - "401": { - "description": "Unauthorized" + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not found" + }, + "503": { + "description": "Private service control is unavailable" + } + }, + "summary": "List private services", + "x-auth": [ + "publishable_key", + "bearer" + ] + }, + "post": { + "description": "Creates one immutable private service in the selected organization.", + "operationId": "post_api_v1_private_services", + "parameters": [], + "requestBody": { + "content": { + "application/json": { + "schema": { + "example": { + "functions": [ + { + "description": "An example description.", + "input_schema": {}, + "name": "Example Name", + "output_schema": {} + } + ], + "org": "string" + }, + "properties": { + "functions": { + "description": "Complete callable contracts. Input schemas are required; output schemas are optional.", + "example": [ + { + "description": "An example description.", + "input_schema": {}, + "name": "Example Name", + "output_schema": {} + } + ], + "items": { + "description": "A documented callable operation exposed by a private service.", + "example": { + "description": "An example description.", + "input_schema": {}, + "name": "Example Name", + "output_schema": {} + }, + "properties": { + "description": { + "description": "Human-readable guidance describing when and why to call the operation.", + "example": "An example description.", + "type": "string" + }, + "input_schema": { + "description": "JSON Schema Draft 7 object describing the operation's argument object.", + "example": {}, + "type": "object" + }, + "name": { + "description": "Stable operation name used when invoking the private service.", + "example": "Example Name", + "type": "string" + }, + "output_schema": { + "description": "Optional JSON Schema Draft 7 object describing the successful result.", + "example": {}, + "type": "object" + } + }, + "required": [ + "name", + "description", + "input_schema" + ], + "type": "object" + }, + "type": "array" + }, + "org": { + "description": "Organization ID or slug. Required for developer and server callers.", + "example": "string", + "type": "string" + } + }, + "required": [ + "functions" + ], + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PrivateService" + } + } + }, + "description": "The newly created private service." + }, + "400": { + "description": "Bad request" }, "403": { - "description": "App-scoped token required. Use a token scoped to the target app.; Forbidden" + "description": "Forbidden" + }, + "404": { + "description": "Not found" + }, + "409": { + "description": "Conflict" + }, + "503": { + "description": "Private service control is unavailable" } }, - "summary": "List customer solution instances", + "summary": "Create a private service", "x-auth": [ "publishable_key", "bearer" ] } }, - "/api/v1/solution_tags": { + "/api/v1/private_services/{private_service_id}": { "get": { - "description": "Returns a paginated list of solution tag definitions visible to the authenticated\nuser, scoped to their app. Results include tags from both the system scope and the\ncaller's organization scope by default; use the `owners` parameter to restrict to\none or both.\n\nUse `keys` to fetch a specific set of tags by their stable key identifiers, or\n`lookup_key` to find a single tag by its lookup key. Use `path_prefix` to filter\ntags by virtual path hierarchy. Combine filters as needed; all supplied filters are\napplied together.\n\nPagination is page-based. Supply `page` and `page_size` to control which page is\nreturned. The response includes `total_entries`, `total_pages`, `has_next`, and\n`has_prev` fields for navigating the full result set.\n", - "operationId": "get_api_v1_solution_tags", + "operationId": "get_api_v1_private_services__private_service_id", "parameters": [ { - "description": "Page number to return. Defaults to 1.", - "example": 1, + "description": "Organization ID or slug. Required for developer and server callers.", + "example": "string", "in": "query", - "name": "page", + "name": "org", "required": false, "schema": { - "type": "integer" + "type": "string" } }, { - "description": "Number of solution tags to return per page. Defaults to 25.", - "example": 1, - "in": "query", - "name": "page_size", - "required": false, + "example": "string", + "in": "path", + "name": "private_service_id", + "required": true, "schema": { - "type": "integer" + "type": "string" } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PrivateService" + } + } + }, + "description": "Successful response" }, - { - "description": "Return only solution tags whose `key` exactly matches one of the provided values.", - "example": [ - "string" - ], - "in": "query", - "name": "keys", - "required": false, - "schema": { - "items": { - "type": "string" - }, - "type": "array" + "400": { + "description": "Bad request" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not found" + }, + "503": { + "description": "Private service control is unavailable" + } + }, + "summary": "Retrieve a private service", + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/sandboxes": { + "post": { + "description": "Creates a new sandbox for the caller's app. A sandbox is an isolated environment\nthat can hold its own set of API keys, allowing you to test integrations without\naffecting production data.\n\nThe caller must authenticate with app-scoped credentials. Org-scoped viewers\nmay create sandboxes for their organization; developers and all-powerful\ncallers may create app-level or org-scoped sandboxes. If `org` is supplied the\nsandbox is scoped to that organization; otherwise it defaults to the\nauthenticated viewer's organization.\n\nRemote-eval sandboxes may set `purpose: \"eval\"` with `expires_at` at creation;\nTTL is the sole cleanup mechanism for those sandboxes. Returns the new sandbox\nwith the auto-issued publishable key — use the create key endpoint to issue\nsecret keys.\n", + "operationId": "post_api_v1_sandboxes", + "parameters": [], + "requestBody": { + "content": { + "application/json": { + "schema": { + "example": { + "expires_at": "2024-01-01T00:00:00Z", + "name": "Example Name", + "org": "string", + "purpose": "string", + "slug": "example-slug" + }, + "properties": { + "expires_at": { + "description": "Optional eval sandbox expiry in ISO 8601 format. Must be paired with `purpose: \"eval\"`.", + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "type": "string" + }, + "name": { + "description": "Human-readable display name for the sandbox.", + "example": "Example Name", + "type": "string" + }, + "org": { + "description": "Organization ID (`org_...`) to scope the sandbox to. Defaults to the authenticated viewer's organization when omitted.", + "example": "string", + "type": "string" + }, + "purpose": { + "description": "Optional sandbox purpose marker. Only `\"eval\"` is accepted, and it must be paired with `expires_at`.", + "example": "string", + "type": "string" + }, + "slug": { + "description": "URL-safe identifier for the sandbox. Must be unique within the app.", + "example": "example-slug", + "type": "string" + } + }, + "required": [ + "name", + "slug" + ], + "type": "object" + } } }, + "required": true + }, + "responses": { + "201": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Sandbox" + } + } + }, + "description": "The newly created sandbox." + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not found" + }, + "422": { + "description": "Validation failed" + } + }, + "summary": "Create a sandbox", + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/sandboxes/{sandbox}": { + "delete": { + "description": "Soft-deletes the specified sandbox. The sandbox is marked deleted and\nimmediately hidden from list/get queries; all of its active keys are revoked.\nHard deletion (child data cascade) is scheduled immediately via the background\nsandbox deletion worker — the same path used for developer-app soft-delete.\n\nThe caller must authenticate with app-scoped credentials and be allowed to\nmodify the sandbox. Returns 204 on success. If the sandbox is missing or\nalready deleted, a 404 is returned.\n", + "operationId": "delete_api_v1_sandboxes__sandbox", + "parameters": [ { - "description": "Return only the solution tag whose `lookup_key` exactly matches this value.", + "description": "Sandbox ID (`dsb_...`) of the sandbox to delete.", "example": "string", - "in": "query", - "name": "lookup_key", - "required": false, + "in": "path", + "name": "sandbox", + "required": true, "schema": { "type": "string" } + } + ], + "responses": { + "204": { + "description": "Empty response with HTTP 204 status on successful deletion." + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" }, + "404": { + "description": "Sandbox not found" + } + }, + "summary": "Delete a sandbox", + "x-auth": [ + "publishable_key", + "bearer" + ] + }, + "get": { + "description": "Returns the sandbox identified by `sandbox` that belongs to the caller's app.\nThe response includes the sandbox's associated keys (without full secret key\nvalues — full keys are only available at creation time).\n\nThe caller must authenticate with app-scoped credentials. Org members may view\ntheir org's sandboxes; developers and all-powerful callers may view app-level\nand org-scoped sandboxes in their app. Returns 404 if the sandbox does not\nexist or is not visible to the caller.\n", + "operationId": "get_api_v1_sandboxes__sandbox", + "parameters": [ { - "description": "Return only solution tags whose `virtual_path` starts with this prefix.", + "description": "Sandbox ID (`dsb_...`) to retrieve.", "example": "string", - "in": "query", - "name": "path_prefix", - "required": false, + "in": "path", + "name": "sandbox", + "required": true, "schema": { "type": "string" } - }, - { - "description": "Restrict results to one or more owner scopes. Accepted values are `\"system\"` (app-level system tags) and `\"org\"` (tags belonging to the caller's organization). Omit to include all scopes visible to the caller.", - "example": [ - "string" - ], - "in": "query", - "name": "owners", - "required": false, - "schema": { - "items": { - "type": "string" - }, - "type": "array" - } } ], "responses": { @@ -40706,78 +43019,153 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SolutionTagListResponse" + "$ref": "#/components/schemas/Sandbox" } } }, - "description": "Paginated list of solution tag definitions visible to the authenticated user." + "description": "The requested sandbox." }, "401": { "description": "Unauthorized" }, "403": { - "description": "Forbidden — app scope required" + "description": "Forbidden" + }, + "404": { + "description": "Sandbox not found" } }, - "summary": "List solution tags", + "summary": "Retrieve a sandbox", "x-auth": [ "publishable_key", "bearer" ] } }, - "/api/v1/solutions": { - "get": { - "description": "Returns a paginated list of Solutions visible to the caller, merging two\nscopes: app-level Solutions (system-owned rows with no org affiliation,\nvisible to everyone — including unauthenticated callers — so they can power\nthe public catalog) and org-level Solutions (system-owned rows stamped with\nthe viewer's org ID, included when an authenticated viewer carries an org\ncontext). Unauthenticated callers resolve to an app-scoped anonymous viewer\nand therefore only ever see the app-level scope.\n\nSolutions that appear under both scopes are deduplicated by their stable\n`solution_id` value. The merged entry's `owners` array lists every scope the\nSolution was found under (`\"system\"` and/or `\"org\"`). When the app-level copy\nhas a higher `solution_version` than the org-level copy, the response includes\n`upgrade_available: true` and `latest_version` so callers can prompt for an\nupgrade.\n", - "operationId": "get_api_v1_solutions", + "/api/v1/sandboxes/{sandbox}/keys": { + "post": { + "description": "Issues a new API key for the specified sandbox. Keys can be either\n`\"publishable\"` (safe to embed in client-side code) or `\"secret\"` (server-side\nonly). The full key value is returned once in the `full_key` field of this\nresponse and is never retrievable again — store it securely immediately.\n\nThe caller must authenticate with app-scoped credentials and be able to\nmodify the sandbox (org members for org sandboxes; developers / all-powerful\nfor app-level). If the sandbox does not belong to the caller's app or is not\nvisible, a 404 is returned. Multiple active keys per sandbox are supported;\nrevoke individual keys with the revoke key endpoint.\n", + "operationId": "post_api_v1_sandboxes__sandbox_keys", "parameters": [ { - "description": "Page number to return. Defaults to `1`.", - "example": 1, - "in": "query", - "name": "page", - "required": false, + "description": "Sandbox ID (`dsb_...`). The key is created for this sandbox.", + "example": "string", + "in": "path", + "name": "sandbox", + "required": true, "schema": { - "type": "integer" + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "example": { + "type": "string" + }, + "properties": { + "type": { + "description": "Key type. One of `\"publishable\"` or `\"secret\"`. Defaults to `\"publishable\"`.", + "example": "string", + "type": "string" + } + }, + "type": "object" + } } }, + "required": true + }, + "responses": { + "201": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SandboxKey" + } + } + }, + "description": "The newly created sandbox key, including the one-time `full_key` value." + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Sandbox not found" + }, + "422": { + "description": "Validation failed" + } + }, + "summary": "Create a sandbox key", + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/slack_channel_bindings": { + "get": { + "description": "Returns a page of Slack channel bindings visible to the authenticated user.\nResults can be filtered by integration, team, agent, or organization. Omit all\nfilter params to retrieve every binding the caller can see.\n\nPagination is page-based. Pass `page` and `per_page` to navigate large result\nsets. `page` must be a positive integer; `per_page` must be between 1 and 100.\nInvalid values return 400.\n", + "operationId": "get_api_v1_slack_channel_bindings", + "parameters": [ { - "description": "Number of Solutions per page. Defaults to `25`.", - "example": 1, + "description": "Return only bindings whose Slack integration matches one of these integration IDs. Omit to return bindings across all integrations.", + "example": [ + "string" + ], "in": "query", - "name": "page_size", + "name": "integration", "required": false, "schema": { - "type": "integer" + "items": { + "type": "string" + }, + "type": "array" } }, { - "description": "Filter to the Solution whose `lookup_key` matches exactly.", - "example": "string", + "description": "Return only bindings bound to one of these team IDs. Omit to return bindings for all teams.", + "example": [ + "string" + ], "in": "query", - "name": "lookup_key", + "name": "team", "required": false, "schema": { - "type": "string" + "items": { + "type": "string" + }, + "type": "array" } }, { - "description": "Filter to Solutions whose `virtual_path` starts with this prefix.", - "example": "string", + "description": "Return only bindings that have at least one of these agent user IDs attached. Omit to return bindings regardless of agent attachment.", + "example": [ + "string" + ], "in": "query", - "name": "path_prefix", + "name": "agent", "required": false, "schema": { - "type": "string" + "items": { + "type": "string" + }, + "type": "array" } }, { - "description": "Restrict results to a subset of owner scopes. Accepted values: `\"system\"` (app-level Solutions) and `\"org\"` (viewer's org-level Solutions). Omit to include all scopes the viewer can see.", + "description": "Return only bindings that belong to one of these organization IDs. Omit to return bindings across all organizations visible to the caller.", "example": [ "string" ], "in": "query", - "name": "owners", + "name": "org", "required": false, "schema": { "items": { @@ -40785,6 +43173,26 @@ }, "type": "array" } + }, + { + "description": "Page number to retrieve, 1-indexed. Defaults to 1. Must be a positive integer.", + "example": 1, + "in": "query", + "name": "page", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "description": "Number of bindings to return per page. Defaults to 25; maximum is 100.", + "example": 1, + "in": "query", + "name": "per_page", + "required": false, + "schema": { + "type": "integer" + } } ], "responses": { @@ -40792,39 +43200,951 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SolutionListResponse" + "$ref": "#/components/schemas/SlackChannelBindingListResponse" } } }, - "description": "Paginated list of Solution summaries visible to the caller." + "description": "Paginated list of Slack channel bindings visible to the caller." + }, + "400": { + "description": "Bad request" }, "401": { "description": "Unauthorized" }, "403": { - "description": "Forbidden — app scope required" + "description": "Forbidden" } }, - "summary": "List Solutions", + "summary": "List Slack channel bindings", "x-auth": [ "publishable_key", "bearer" ] }, "post": { - "description": "Imports a Solution and its bundled configs (skills, scripts, templates, files)\ninto the library for the target scope. Two mutually exclusive import modes\nare supported: pass `solution` to re-import an existing system-owned catalog\nSolution by ID or `lookup_key`, or pass `solution_bundle` to supply a\nself-contained inline bundle. Exactly one must be present.\n\nThe operation upserts the bundle in a single transaction. When `dry_run` is\n`true` the same pipeline runs but the transaction is rolled back — no rows are\npersisted and the response reflects what would have been written. The\nresponse shape is the same in both cases: the Solution summary plus\n`installed_configs` listing each config the import created or would create.\n\nPairs with `POST /api/v1/solutions/:solution/install`: this endpoint puts the\nSolution into the library; install provisions a runtime resource (Agent,\nAgentRoutine, AgentTool, etc.) from an already-imported Solution.\n", - "operationId": "post_api_v1_solutions", + "description": "Creates a new binding between a Slack channel and a team, or updates the\nexisting binding if one already exists for the given channel. The caller also\nsupplies a list of agents to attach to the binding and enroll as members of the\ndestination team.\n\nThe caller must have team-manage rights on the destination team (and on the\ncurrently bound team if the channel is being re-pointed). Returns 403 if\npermission is insufficient. All write steps are idempotent, so retrying after\na partial failure is safe.\n\nOn success the REST endpoint returns 201 Created. The script binding\n(`slack.channel_bindings.upsert`) returns the full binding object including the\nattached agents.\n", + "operationId": "post_api_v1_slack_channel_bindings", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "example": { - "dry_run": true, - "org": "string", - "solution": "string", - "solution_bundle": { - "configs": [ + "agent_user_ids": [ + "string" + ], + "allow_bot_conversations": true, + "channel_id": "string", + "customer_label": "string", + "is_ext_shared_cached": true, + "is_private_cached": true, + "slack_team_id": "string", + "team_id": "string" + }, + "properties": { + "agent_user_ids": { + "description": "List of agent user IDs to attach to the binding and enroll as members of the destination team. Pass an empty array to bind the channel without attaching any agents.", + "example": [ + "string" + ], + "items": { + "type": "string" + }, + "type": "array" + }, + "allow_bot_conversations": { + "description": "Opt this channel into sustained bot-to-bot conversation: the reply loop brake is disabled for its mirror thread. Set when the counterparty is a known bot the agent should keep answering. Omitting the parameter leaves the stored value unchanged.", + "example": true, + "type": "boolean" + }, + "channel_id": { + "description": "Slack channel ID to bind (e.g. `C01234ABCDE`). Acts as the natural key of the binding within the workspace.", + "example": "string", + "type": "string" + }, + "customer_label": { + "description": "Human-readable label for the customer associated with this channel. Stored in the binding's config. `null` if omitted.", + "example": "string", + "type": "string" + }, + "is_ext_shared_cached": { + "description": "Cached value of Slack's `is_ext_shared` flag for the channel. When provided, this value is persisted on the binding to avoid repeated Slack API lookups. `null` if omitted.", + "example": true, + "type": "boolean" + }, + "is_private_cached": { + "description": "Cached value of Slack's `is_private` flag for the channel. When provided, this value is persisted on the binding to avoid repeated Slack API lookups. Private channels are member-managed. `null` if omitted.", + "example": true, + "type": "boolean" + }, + "slack_team_id": { + "description": "Slack workspace team ID that the channel belongs to (e.g. `T01234ABCDE`). Identifies which Slack integration to use.", + "example": "string", + "type": "string" + }, + "team_id": { + "description": "ID of the team to bind the Slack channel to. The caller must have team-manage rights on this team.", + "example": "string", + "type": "string" + } + }, + "required": [ + "slack_team_id", + "channel_id", + "team_id", + "agent_user_ids" + ], + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SlackChannelBinding" + } + } + }, + "description": "The created or updated Slack channel binding, including the full list of currently attached agents." + }, + "400": { + "description": "Bad request" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden; The Slack integration referenced by this binding is not visible to the caller" + }, + "404": { + "description": "Agent not found; Team not found" + }, + "409": { + "description": "Channel already has a resident agent" + }, + "422": { + "description": "Invalid parameters; Binding org_id does not match the integration's org_id" + } + }, + "summary": "Create or update a Slack channel binding", + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/slack_channel_bindings/provision": { + "post": { + "description": "Opens a Slack Connect channel with a new customer — creating one and sending\nthe invite, or adopting a shared channel you already have — and records who is\nadding whom so the addition can finish once the customer accepts.\n\nThe returned binding is **pending**: nothing mirrors, and no per-customer Team,\nagent, or solution instance exists yet. Acceptance is asynchronous and may\nnever come. When it does, the addition completes in the background under the\nidentity of the admin who called this endpoint, re-checked live at that moment.\nA caller who has since lost their admin role does not get a substitute — the\naddition is refused and a human re-adds the customer.\n\nThe caller must be an admin of the Slack integration's own organization. This\nis the same authority the completion demands, checked here so a customer is\nnever invited into a channel whose addition can never finish.\n\nDeliberately not exposed as a script binding: this sends mail to a person\noutside the org, so it stays a vendor-admin HTTP surface.\n", + "operationId": "post_api_v1_slack_channel_bindings_provision", + "parameters": [], + "requestBody": { + "content": { + "application/json": { + "schema": { + "example": { + "channel_name": "Example Name", + "customer_email": "user@example.com", + "customer_key": "string", + "customer_label": "string", + "existing_channel_id": "string", + "inputs": {}, + "slack_team_id": "string", + "template_config_id": "string" + }, + "properties": { + "channel_name": { + "description": "Name for a Slack channel to create for this customer. Required unless `existing_channel_id` is given. The channel is created private.", + "example": "Example Name", + "type": "string" + }, + "customer_email": { + "description": "Address the Slack Connect invite is sent to. Required when creating a channel; optional when adopting one the customer is already in. Whoever accepts becomes the verified counterparty.", + "example": "user@example.com", + "type": "string" + }, + "customer_key": { + "description": "The vendor's own primary key for this customer (`customer_id` / `account_id` / `tenant_id`). The per-customer agent's data access is locked to it. Immutable once the customer is added: re-targeting means offboarding and re-provisioning.", + "example": "string", + "type": "string" + }, + "customer_label": { + "description": "Human-readable name for the customer (e.g. `Acme, Inc.`). Used for the vendor's own dashboards and as the per-customer Team's name. Not an identity or an access control input.", + "example": "string", + "type": "string" + }, + "existing_channel_id": { + "description": "Adopt this already-shared Slack Connect channel (e.g. `C01234ABCDE`) instead of creating one. Mutually exclusive with `channel_name`.", + "example": "string", + "type": "string" + }, + "inputs": { + "description": "String-keyed values the per-customer solution instance is stamped with. Defaults to an empty map.", + "example": {}, + "type": "object" + }, + "slack_team_id": { + "description": "Slack workspace team ID of the vendor's own Slack installation (e.g. `T01234ABCDE`). The customer's workspace is not known yet — it resolves from whoever accepts.", + "example": "string", + "type": "string" + }, + "template_config_id": { + "description": "Config ID (`cfg_…`) of the org-installed Solution the per-customer instance is stamped from. Must be the organization's own installed copy, not the catalog original — instances stamped from a different config do not appear in the vendor's customer fleet.", + "example": "string", + "type": "string" + } + }, + "required": [ + "slack_team_id", + "customer_label", + "customer_key", + "template_config_id" + ], + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SlackChannelBinding" + } + } + }, + "description": "The pending binding for the customer's channel. `disclosure_state` is `pending` until the customer accepts, and `scope_key` is null until the addition finishes." + }, + "400": { + "description": "Bad request" + }, + "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" + }, + "409": { + "description": "Conflict" + }, + "422": { + "description": "Invalid parameters" + }, + "500": { + "description": "Internal server error" + }, + "502": { + "description": "Provider returned an error; Service unavailable" + } + }, + "summary": "Start adding a customer over Slack Connect", + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/slack_channel_bindings/{channel}": { + "delete": { + "description": "Removes the binding between a Slack channel and its associated team. The\nchannel is identified by its Slack channel ID together with the `slack_team_id`\nthat scopes it to a specific Slack workspace. Removing the binding does not\ndelete the bound team or any conversation threads scoped to it; decommission\nthose resources separately if required.\n\nThe caller must have team-manage rights on the team the channel is currently\nbound to. Returning 403 indicates insufficient permission; returning 404\nindicates the binding does not exist or is not visible to the caller.\n\nThe REST endpoint returns 204 No Content on success. The script binding\n(`slack.channel_bindings.delete`) returns a confirmation object so script\ncallers can verify success without an additional fetch. Both paths are\nidempotent — retrying after a partial failure is safe.\n", + "operationId": "delete_api_v1_slack_channel_bindings__channel", + "parameters": [ + { + "description": "Slack channel ID of the binding to delete (e.g. `C01234ABCDE`).", + "example": "string", + "in": "path", + "name": "channel", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "description": "Deletion confirmation returned by the script binding. The REST endpoint returns 204 No Content with no body.", + "example": { + "channel": "string", + "deleted": true + }, + "properties": { + "channel": { + "description": "Slack channel ID of the binding that was deleted.", + "example": "string", + "type": "string" + }, + "deleted": { + "description": "Always `true` when the binding was successfully removed.", + "example": true, + "type": "boolean" + } + }, + "required": [ + "deleted", + "channel" + ], + "type": "object" + } + } + }, + "description": "Successful response" + }, + "400": { + "description": "Bad request" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden; The Slack integration referenced by this binding is not visible to the caller" + }, + "404": { + "description": "Slack channel binding not found" + }, + "422": { + "description": "Invalid parameters" + } + }, + "summary": "Delete a Slack channel binding", + "x-auth": [ + "publishable_key", + "bearer" + ] + }, + "get": { + "description": "Returns the Slack channel binding identified by a Slack channel ID and workspace\nteam ID pair. Use this endpoint to look up the team and agents currently bound\nto a specific Slack channel.\n\nThe `channel` path parameter is the Slack channel ID; `slack_team_id` identifies\nthe Slack workspace the channel belongs to, disambiguating channels with the same\nID across workspaces. Both parameters are required. Returns 404 if no binding\nexists for the given pair or the associated Slack integration is not visible to\nthe caller.\n", + "operationId": "get_api_v1_slack_channel_bindings__channel", + "parameters": [ + { + "description": "Slack channel ID of the binding to retrieve (e.g. `C01234ABCDE`).", + "example": "string", + "in": "path", + "name": "channel", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Slack workspace team ID that the channel belongs to (e.g. `T01234ABCDE`). Used together with `channel` to uniquely identify the binding.", + "example": "string", + "in": "query", + "name": "slack_team_id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SlackChannelBinding" + } + } + }, + "description": "The Slack channel binding for the given channel and workspace." + }, + "400": { + "description": "Bad request" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "The Slack integration referenced by this binding is not visible to the caller" + }, + "404": { + "description": "Slack channel binding not found" + }, + "422": { + "description": "Invalid parameters" + } + }, + "summary": "Retrieve a Slack channel binding", + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/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", + "operationId": "post_api_v1_slack_channel_bindings__channel_deposit_thread", + "parameters": [ + { + "description": "Slack channel ID whose binding is being configured (e.g. `C01234ABCDE`).", + "example": "string", + "in": "path", + "name": "channel", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "example": { + "slack_team_id": "string", + "thread_id": "string" + }, + "properties": { + "slack_team_id": { + "description": "Slack workspace team ID that the channel belongs to (e.g. `T01234ABCDE`). Identifies which Slack integration to use.", + "example": "string", + "type": "string" + }, + "thread_id": { + "description": "Staging thread ID (primary key, `thr_…`) deposits should flow into. Pass `null` to turn the pipe off.", + "example": "string", + "type": "string" + } + }, + "required": [ + "slack_team_id" + ], + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SlackChannelBinding" + } + } + }, + "description": "The binding with the updated deposit config." + }, + "400": { + "description": "Bad request" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden; The Slack integration referenced by this binding is not visible to the caller" + }, + "404": { + "description": "Not found" + }, + "422": { + "description": "Invalid parameters" + } + }, + "summary": "Point a Slack channel's deposit pipe at a staging thread, or turn it off", + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/solution_categories": { + "get": { + "description": "Returns a paginated list of solution category definitions visible to the authenticated caller.\nUse filters to narrow results by key, parent key, lookup key, or virtual path prefix.\n\nResults are scoped to categories accessible under the caller's viewer context. Pass `app` to\nrestrict the listing to categories associated with a specific app scope. Omit `owners` to\nreturn categories from all ownership scopes (`\"system\"` and `\"org\"`) that the caller can see.\n\nPagination is page-based. Use `page` and `page_size` to navigate large result sets. The\nresponse includes `total_entries`, `total_pages`, `has_next`, and `has_prev` to support\npagination controls. `total_entries` reflects the count after key deduplication.\n", + "operationId": "get_api_v1_solution_categories", + "parameters": [ + { + "description": "Page number to retrieve, 1-indexed. Defaults to `1`.", + "example": 1, + "in": "query", + "name": "page", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "description": "Number of solution categories to return per page. Defaults to `25`.", + "example": 1, + "in": "query", + "name": "page_size", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "description": "Return only categories whose key exactly matches one of the provided values.", + "example": [ + "string" + ], + "in": "query", + "name": "keys", + "required": false, + "schema": { + "items": { + "type": "string" + }, + "type": "array" + } + }, + { + "description": "Return only categories whose parent key matches one of the provided values. Pass an empty array to return root-level categories.", + "example": [ + "string" + ], + "in": "query", + "name": "parent_keys", + "required": false, + "schema": { + "items": { + "type": "string" + }, + "type": "array" + } + }, + { + "description": "Return only the category whose `lookup_key` exactly matches this value.", + "example": "string", + "in": "query", + "name": "lookup_key", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Return only categories whose `virtual_path` starts with this prefix.", + "example": "string", + "in": "query", + "name": "path_prefix", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Restrict results to categories owned by the specified scopes. Accepted values are `\"system\"` and `\"org\"`. Omit to include all ownership scopes visible to the caller.", + "example": [ + "string" + ], + "in": "query", + "name": "owners", + "required": false, + "schema": { + "items": { + "type": "string" + }, + "type": "array" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SolutionCategoryListResponse" + } + } + }, + "description": "Paginated list of solution category summaries matching the applied filters." + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden — app scope required" + } + }, + "summary": "List solution categories", + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/solution_instances": { + "get": { + "description": "Returns a forward cursor-paginated page of customer instances stamped from one\nsolution template. Results are restricted to the caller's organization; an\napp-wide viewer without an organization scope is forbidden.\n\nPass `after_cursor` from a response with `has_more: true` to retrieve the next\npage. Each row includes the materialized agent, pinned template version, and\nlocal-edit count computed by the solution-instance read path.\n", + "operationId": "get_api_v1_solution_instances", + "parameters": [ + { + "description": "ID of the installed solution template whose customer instances should be listed.", + "example": "string", + "in": "query", + "name": "solution_template_config_id", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Maximum number of instances 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. Omit to retrieve the first page.", + "example": "string", + "in": "query", + "name": "after_cursor", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SolutionInstanceListResponse" + } + } + }, + "description": "Cursor-paginated customer solution instances visible to the caller." + }, + "400": { + "description": "Bad request; Invalid cursor" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "App-scoped token required. Use a token scoped to the target app.; Forbidden" + } + }, + "summary": "List customer solution instances", + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/solution_tags": { + "get": { + "description": "Returns a paginated list of solution tag definitions visible to the authenticated\nuser, scoped to their app. Results include tags from both the system scope and the\ncaller's organization scope by default; use the `owners` parameter to restrict to\none or both.\n\nUse `keys` to fetch a specific set of tags by their stable key identifiers, or\n`lookup_key` to find a single tag by its lookup key. Use `path_prefix` to filter\ntags by virtual path hierarchy. Combine filters as needed; all supplied filters are\napplied together.\n\nPagination is page-based. Supply `page` and `page_size` to control which page is\nreturned. The response includes `total_entries`, `total_pages`, `has_next`, and\n`has_prev` fields for navigating the full result set.\n", + "operationId": "get_api_v1_solution_tags", + "parameters": [ + { + "description": "Page number to return. Defaults to 1.", + "example": 1, + "in": "query", + "name": "page", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "description": "Number of solution tags to return per page. Defaults to 25.", + "example": 1, + "in": "query", + "name": "page_size", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "description": "Return only solution tags whose `key` exactly matches one of the provided values.", + "example": [ + "string" + ], + "in": "query", + "name": "keys", + "required": false, + "schema": { + "items": { + "type": "string" + }, + "type": "array" + } + }, + { + "description": "Return only the solution tag whose `lookup_key` exactly matches this value.", + "example": "string", + "in": "query", + "name": "lookup_key", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Return only solution tags whose `virtual_path` starts with this prefix.", + "example": "string", + "in": "query", + "name": "path_prefix", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Restrict results to one or more owner scopes. Accepted values are `\"system\"` (app-level system tags) and `\"org\"` (tags belonging to the caller's organization). Omit to include all scopes visible to the caller.", + "example": [ + "string" + ], + "in": "query", + "name": "owners", + "required": false, + "schema": { + "items": { + "type": "string" + }, + "type": "array" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SolutionTagListResponse" + } + } + }, + "description": "Paginated list of solution tag definitions visible to the authenticated user." + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden — app scope required" + } + }, + "summary": "List solution tags", + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/solutions": { + "get": { + "description": "Returns a paginated list of Solutions visible to the caller, merging two\nscopes: app-level Solutions (system-owned rows with no org affiliation,\nvisible to everyone — including unauthenticated callers — so they can power\nthe public catalog) and org-level Solutions (system-owned rows stamped with\nthe viewer's org ID, included when an authenticated viewer carries an org\ncontext). Unauthenticated callers resolve to an app-scoped anonymous viewer\nand therefore only ever see the app-level scope.\n\nSolutions that appear under both scopes are deduplicated by their stable\n`solution_id` value. The merged entry's `owners` array lists every scope the\nSolution was found under (`\"system\"` and/or `\"org\"`). When the app-level copy\nhas a higher `solution_version` than the org-level copy, the response includes\n`upgrade_available: true` and `latest_version` so callers can prompt for an\nupgrade.\n", + "operationId": "get_api_v1_solutions", + "parameters": [ + { + "description": "Page number to return. Defaults to `1`.", + "example": 1, + "in": "query", + "name": "page", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "description": "Number of Solutions per page. Defaults to `25`.", + "example": 1, + "in": "query", + "name": "page_size", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "description": "Filter to the Solution whose `lookup_key` matches exactly.", + "example": "string", + "in": "query", + "name": "lookup_key", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Filter to Solutions whose `virtual_path` starts with this prefix.", + "example": "string", + "in": "query", + "name": "path_prefix", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Restrict results to a subset of owner scopes. Accepted values: `\"system\"` (app-level Solutions) and `\"org\"` (viewer's org-level Solutions). Omit to include all scopes the viewer can see.", + "example": [ + "string" + ], + "in": "query", + "name": "owners", + "required": false, + "schema": { + "items": { + "type": "string" + }, + "type": "array" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SolutionListResponse" + } + } + }, + "description": "Paginated list of Solution summaries visible to the caller." + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden — app scope required" + } + }, + "summary": "List Solutions", + "x-auth": [ + "publishable_key", + "bearer" + ] + }, + "post": { + "description": "Imports a Solution and its bundled configs (skills, scripts, templates, files)\ninto the library for the target scope. Two mutually exclusive import modes\nare supported: pass `solution` to re-import an existing system-owned catalog\nSolution by ID or `lookup_key`, or pass `solution_bundle` to supply a\nself-contained inline bundle. Exactly one must be present.\n\nThe operation upserts the bundle in a single transaction. When `dry_run` is\n`true` the same pipeline runs but the transaction is rolled back — no rows are\npersisted and the response reflects what would have been written. The\nresponse shape is the same in both cases: the Solution summary plus\n`installed_configs` listing each config the import created or would create.\n\nPairs with `POST /api/v1/solutions/:solution/install`: this endpoint puts the\nSolution into the library; install provisions a runtime resource (Agent,\nAgentRoutine, AgentTool, etc.) from an already-imported Solution.\n", + "operationId": "post_api_v1_solutions", + "parameters": [], + "requestBody": { + "content": { + "application/json": { + "schema": { + "example": { + "dry_run": true, + "org": "string", + "solution": "string", + "solution_bundle": { + "configs": [ { "content": "string", "content_type": "application/json", @@ -42072,6 +45392,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 +46303,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 +46316,9 @@ "owner_user": "string", "parent": "string", "priority": 1, + "source_id": "string", + "source_scope": "string", + "source_type": "string", "status": "string", "tags": [ "string" @@ -42969,6 +46343,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 +46400,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 +46768,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -43403,6 +46798,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 +46854,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -43485,6 +46884,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 +46929,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -43556,6 +46959,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 +46976,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 +46988,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,20 +47018,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": { @@ -43637,40 +47049,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" } }, @@ -43682,11 +47102,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": { @@ -43725,12 +47147,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": { @@ -43765,6 +47195,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": { @@ -43783,20 +47214,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": { @@ -43810,40 +47245,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" } }, @@ -43855,16 +47298,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 +47321,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 +47365,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 +47383,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 +47679,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -44240,6 +47709,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 +47765,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -44322,6 +47795,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 +47840,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -44393,6 +47870,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 +47887,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 +47899,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 +47929,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 +47960,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 +48013,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 +48058,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 +48106,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 +48125,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 +48156,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 +48209,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 +48232,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 +48276,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 +48294,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 +48541,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 +48567,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 +49032,7 @@ "harness": "string", "lease_duration_seconds": 1, "lease_id": "string", + "require_ready": true, "session_id": "string", "session_name": "Example Name" }, @@ -45499,6 +49053,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 +49203,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 +49435,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -45787,6 +49465,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 +49521,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -45869,6 +49551,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 +49596,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -45940,6 +49626,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 +49643,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 +49655,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 +49685,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 +49716,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 +49769,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 +49814,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 +49862,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 +49881,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 +49912,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 +49965,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 +49988,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 +50032,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 +50050,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 +50216,9 @@ "401": { "description": "Unauthorized" }, + "403": { + "description": "Forbidden" + }, "404": { "description": "Team or member not found" } @@ -46798,6 +50552,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -46949,6 +50704,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 +50716,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 +50727,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 +50745,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 +51765,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 +52926,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 +52941,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -49384,6 +53158,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 +53173,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -49607,6 +53387,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 +53402,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -49805,6 +53591,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 +53623,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -49986,23 +53774,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 +53803,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 +53833,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 +53991,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 +54066,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 +54088,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 +54099,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 +54124,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 +54144,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 +54194,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 +54216,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 +54232,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 +54254,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 +54287,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 +54295,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -50499,12 +54320,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 +54342,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": { @@ -50548,6 +54372,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": { @@ -50573,6 +54398,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -50621,11 +54447,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 +54464,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 +54495,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 +54506,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 +54592,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 +54614,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 +54625,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 +54650,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 +54670,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 +54720,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 +54742,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 +54758,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 +54780,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 +54813,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 +54821,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -50992,12 +54846,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 +54868,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": { @@ -51041,6 +54898,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": { @@ -51066,6 +54924,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -51114,11 +54973,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 +54990,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 +55021,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 +55032,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 +55068,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 +55090,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 +55108,7 @@ "virtual_path": { "description": "Virtual filesystem path for this template config. `null` if not set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -51258,22 +55128,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 +55181,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 +55195,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 +55250,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 +55270,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 +55285,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 +55365,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 +55442,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": [ { @@ -51589,103 +55524,548 @@ "operationId": "patch_api_v1_teams__team_members__user", "parameters": [ { - "description": "Team ID (`team_...`). The team whose member role you want to update.", + "description": "Team ID (`team_...`). The team whose member role you want to update.", + "example": "string", + "in": "path", + "name": "team", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "User ID (`usr_...`) of the existing member whose role should be changed.", + "example": "string", + "in": "path", + "name": "user", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "example": { + "role": "string" + }, + "properties": { + "role": { + "description": "New role to assign. One of `\"owner\"`, `\"admin\"`, or `\"member\"`.", + "example": "string", + "type": "string" + } + }, + "required": [ + "role" + ], + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TeamMembership" + } + } + }, + "description": "The updated team membership reflecting the new role." + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden — caller lacks permission to modify this team" + }, + "404": { + "description": "Team or member not found" + }, + "409": { + "description": "Conflict — cannot demote the last owner" + }, + "422": { + "description": "Validation failed (e.g. invalid role)" + } + }, + "summary": "Update a team member's role", + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/teams/{team}/task_assignees": { + "get": { + "description": "Returns the list of principals — users and agents — that can be assigned\nto tasks within the team. Results include both human members and AI agents\nand are sorted alphabetically by display name.\n\nThis endpoint is only available for team-scoped contexts. Calling it with a\nuser-scoped owner returns a 400 error. The authenticated user must be a\nmember of the team or hold org-admin access. App-scoped developer and\nserver-to-server callers may list assignees for teams in their app so they\ncan select the explicit user or agent actor required by privileged task\nmutations.\n", + "operationId": "get_api_v1_teams__team_task_assignees", + "parameters": [ + { + "description": "Team ID (`tem_...`).", + "example": "string", + "in": "path", + "name": "team", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Explicit organization (`org_...`) for developer and server-to-server calls. Pass null for a team outside an organization.", + "example": "string", + "in": "query", + "name": "org", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "description": "Assignable users and agents for the team.", + "example": { + "data": [ + { + "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": "string", + "type": "user" + } + ] + }, + "properties": { + "data": { + "description": "Users and agents that can be assigned to tasks owned by the team.", + "example": [ + { + "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": "string", + "type": "user" + } + ], + "items": { + "description": "A user or agent that can be assigned to a team-owned task.", + "example": { + "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": "string", + "type": "user" + }, + "properties": { + "actor": { + "description": "Resolved display details for the assignable principal.", + "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": { + "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" + }, + "id": { + "description": "User (`usr_...`) or agent (`agi_...`) ID.", + "example": "string", + "type": "string" + }, + "type": { + "description": "Principal type: `user` or `agent`.", + "enum": [ + "user", + "agent" + ], + "example": "user", + "type": "string" + } + }, + "required": [ + "id", + "type", + "actor" + ], + "type": "object" + }, + "type": "array" + } + }, + "required": [ + "data" + ], + "type": "object" + } + } + }, + "description": "Successful response" + }, + "401": { + "description": "Unauthorized" + }, + "404": { + "description": "Task owner not found" + }, + "422": { + "description": "Invalid explicit owner or organization context" + } + }, + "summary": "List task assignees for a team", + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/teams/{team}/tasks": { + "get": { + "description": "Returns tasks owned by the specified user or team. You can narrow results using the\noptional filters below. By default results are returned in reverse chronological\norder (most recently created first); use `sort` and `order` to sort by due date or\npriority instead.\n\nUser-authenticated callers may list their personal tasks or tasks for teams they\nhave 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", + "parameters": [ + { + "description": "Team ID (`tem_...`). Only tasks belonging to this team are returned.", + "example": "string", + "in": "path", + "name": "team", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "User ID (`usr_...`) for user-scoped tasks.", + "example": "string", + "in": "query", + "name": "user", + "required": false, + "schema": { + "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": "Filter tasks by status. One of `\"open\"`, `\"in_progress\"`, or `\"done\"`. Omit to return tasks in all statuses.", + "example": "string", + "in": "query", + "name": "status", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Filter tasks assigned to a specific user. Provide the user's public ID (`usr_...`).", + "example": "string", + "in": "query", + "name": "owner_user", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Filter tasks assigned to a specific agent. Provide the agent's public ID (`agi_...`).", + "example": "string", + "in": "query", + "name": "owner_agent", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Filter tasks 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. 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": "path", - "name": "team", - "required": true, + "in": "query", + "name": "epic", + "required": false, "schema": { "type": "string" } }, { - "description": "User ID (`usr_...`) of the existing member whose role should be changed.", + "description": "Restrict results to tasks whose name or description contains this string.", "example": "string", - "in": "path", - "name": "user", - "required": true, + "in": "query", + "name": "search", + "required": false, "schema": { "type": "string" } - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "example": { - "role": "string" - }, - "properties": { - "role": { - "description": "New role to assign. One of `\"owner\"`, `\"admin\"`, or `\"member\"`.", - "example": "string", - "type": "string" - } - }, - "required": [ - "role" - ], - "type": "object" - } + }, + { + "description": "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.", + "example": "string", + "in": "query", + "name": "sort", + "required": false, + "schema": { + "type": "string" } }, - "required": true - }, - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TeamMembership" - } - } - }, - "description": "The updated team membership reflecting the new role." + { + "description": "Sort direction, `\"asc\"` or `\"desc\"`. Defaults to `\"desc\"` for `created` and `\"asc\"` for `due_date` and `priority`.", + "example": "string", + "in": "query", + "name": "order", + "required": false, + "schema": { + "type": "string" + } }, - "401": { - "description": "Unauthorized" + { + "description": "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.", + "example": "string", + "in": "query", + "name": "due_before", + "required": false, + "schema": { + "type": "string" + } }, - "403": { - "description": "Forbidden — caller lacks permission to modify this team" + { + "description": "Return only tasks with a due date strictly after this ISO 8601 datetime or date. Tasks without a due date are excluded.", + "example": "string", + "in": "query", + "name": "due_after", + "required": false, + "schema": { + "type": "string" + } }, - "404": { - "description": "Team or member not found" + { + "description": "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.", + "example": true, + "in": "query", + "name": "overdue", + "required": false, + "schema": { + "type": "boolean" + } }, - "409": { - "description": "Conflict — cannot demote the last owner" + { + "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" + } }, - "422": { - "description": "Validation failed (e.g. invalid role)" - } - }, - "summary": "Update a team member's role", - "x-auth": [ - "publishable_key", - "bearer" - ] - } - }, - "/api/v1/teams/{team}/task_assignees": { - "get": { - "description": "Returns the list of principals — users and agents — that can be assigned\nto tasks within the team. Results include both human members and AI agents\nand are sorted alphabetically by display name.\n\nThis endpoint is only available for team-scoped contexts. Calling it with a\nuser-scoped owner returns a 400 error. The authenticated user must be a\nmember of the team or hold org-admin access. App-scoped developer and\nserver-to-server callers may list assignees for teams in their app so they\ncan select the explicit user or agent actor required by privileged task\nmutations.\n", - "operationId": "get_api_v1_teams__team_task_assignees", - "parameters": [ { - "description": "Team ID (`tem_...`).", - "example": "string", - "in": "path", - "name": "team", - "required": true, + "description": "Maximum number of tasks to return. Capped at 100.", + "example": 1, + "in": "query", + "name": "limit", + "required": false, "schema": { - "type": "string" + "type": "integer" } }, { - "description": "Explicit organization (`org_...`) for developer and server-to-server calls. Pass null for a team outside an organization.", + "description": "Opaque cursor returned by the previous page.", "example": "string", "in": "query", - "name": "org", + "name": "after_cursor", "required": false, "schema": { "type": "string" @@ -51697,11 +56077,18 @@ "content": { "application/json": { "schema": { - "description": "Assignable users and agents for the team.", + "description": "Filtered list of tasks for the owner.", "example": { + "after_cursor": "string", + "before_cursor": "string", "data": [ { - "actor": { + "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", @@ -51715,17 +56102,191 @@ "width": 800 } }, - "id": "string", - "type": "user" + "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", + "nullable": true, + "type": "string" + }, + "before_cursor": { + "example": "string", + "nullable": true, + "type": "string" + }, "data": { - "description": "Users and agents that can be assigned to tasks owned by the team.", + "description": "Array of task objects matching the requested filters.", "example": [ { - "actor": { + "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", @@ -51739,33 +56300,252 @@ "width": 800 } }, - "id": "string", - "type": "user" - } - ], - "items": { - "description": "A user or agent that can be assigned to a team-owned task.", - "example": { - "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" }, - "id": "string", - "type": "user" - }, - "properties": { - "actor": { - "description": "Resolved display details for the assignable principal.", + "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", @@ -51780,20 +56560,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": { @@ -51807,40 +56591,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" } }, @@ -51849,33 +56641,115 @@ }, "type": "object" }, - "id": { - "description": "User (`usr_...`) or agent (`agi_...`) ID.", + "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" }, - "type": { - "description": "Principal type: `user` or `agent`.", - "enum": [ - "user", - "agent" + "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" ], - "example": "user", + "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", - "type", - "actor" + "name", + "status" ], "type": "object" }, "type": "array" + }, + "has_more": { + "example": true, + "type": "boolean" } }, "required": [ - "data" + "data", + "has_more" ], "type": "object" } @@ -51893,20 +56767,18 @@ "description": "Invalid explicit owner or organization context" } }, - "summary": "List task assignees for a team", + "summary": "List an owner's tasks", "x-auth": [ "publishable_key", "bearer" ] - } - }, - "/api/v1/teams/{team}/tasks": { - "get": { - "description": "Returns tasks owned by the specified user or team. You can narrow results using the\noptional filters below. By default results are returned in reverse chronological\norder (most recently created first); use `sort` and `order` to sort by due date or\npriority instead.\n\nUser-authenticated callers may list their personal tasks or tasks for teams they\nhave 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", + }, + "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_teams__team_tasks", "parameters": [ { - "description": "Team ID (`tem_...`). Only tasks belonging to this team are returned.", + "description": "Team ID (`tem_...`). The task will be owned by this team.", "example": "string", "in": "path", "name": "team", @@ -51914,149 +56786,258 @@ "schema": { "type": "string" } - }, - { - "description": "User ID (`usr_...`) for user-scoped tasks.", - "example": "string", - "in": "query", - "name": "user", - "required": false, - "schema": { - "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": "Filter tasks by status. One of `\"open\"`, `\"in_progress\"`, or `\"done\"`. Omit to return tasks in all statuses.", - "example": "string", - "in": "query", - "name": "status", - "required": false, - "schema": { - "type": "string" - } - }, - { - "description": "Filter tasks assigned to a specific user. Provide the user's public ID (`usr_...`).", - "example": "string", - "in": "query", - "name": "owner_user", - "required": false, - "schema": { - "type": "string" - } - }, - { - "description": "Filter tasks assigned to a specific agent. Provide the agent's public ID (`agi_...`).", - "example": "string", - "in": "query", - "name": "owner_agent", - "required": false, - "schema": { - "type": "string" - } - }, - { - "description": "Filter tasks 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" + } + ], + "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" + }, + "user": "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" + }, + "user": { + "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", + "type": "string" + } + }, + "required": [ + "task" + ], + "type": "object" + } } }, - { - "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" - } + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Task" + } + } + }, + "description": "The newly created task." }, - { - "description": "Restrict results to tasks whose name or description contains this string.", - "example": "string", - "in": "query", - "name": "search", - "required": false, - "schema": { - "type": "string" - } + "401": { + "description": "Unauthorized" }, - { - "description": "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.", - "example": "string", - "in": "query", - "name": "sort", - "required": false, - "schema": { - "type": "string" - } + "404": { + "description": "Task owner not found" }, + "422": { + "description": "Validation error" + } + }, + "summary": "Create a task for an owner", + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/teams/{team}/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_teams__team_tasks_blocker_cycles", + "parameters": [ { - "description": "Sort direction, `\"asc\"` or `\"desc\"`. Defaults to `\"desc\"` for `created` and `\"asc\"` for `due_date` and `priority`.", + "description": "Team ID (`tem_...`) owning the tasks.", "example": "string", - "in": "query", - "name": "order", - "required": false, + "in": "path", + "name": "team", + "required": true, "schema": { "type": "string" } }, { - "description": "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.", + "description": "User ID (`usr_...`) owning the tasks.", "example": "string", "in": "query", - "name": "due_before", + "name": "user", "required": false, "schema": { "type": "string" } }, { - "description": "Return only tasks with a due date strictly after this ISO 8601 datetime or date. Tasks without a due date are excluded.", + "description": "Optional organization context for privileged callers.", "example": "string", "in": "query", - "name": "due_after", + "name": "org", "required": false, "schema": { "type": "string" } }, { - "description": "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.", - "example": true, - "in": "query", - "name": "overdue", - "required": false, - "schema": { - "type": "boolean" - } - }, - { - "description": "Maximum number of tasks to return. Capped at 100.", + "description": "Maximum cycle components to return. Defaults to 50; maximum is 100.", "example": 1, "in": "query", "name": "limit", @@ -52066,7 +57047,7 @@ } }, { - "description": "Opaque cursor returned by the previous page.", + "description": "Opaque cursor returned by the preceding page.", "example": "string", "in": "query", "name": "after_cursor", @@ -52081,264 +57062,20 @@ "content": { "application/json": { "schema": { - "description": "Filtered list of tasks for the owner.", + "description": "On-demand task blocker cycle diagnostics.", "example": { "after_cursor": "string", "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 - }, - "properties": { - "after_cursor": { - "example": "string", - "type": "string" - }, - "before_cursor": { - "example": "string", - "type": "string" - }, - "data": { - "description": "Array of task objects matching the requested 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 - } - }, - "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" - } - ], - "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", - "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": { + "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", @@ -52352,166 +57089,27 @@ "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": { + "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", @@ -52525,25 +57123,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 + } + }, + "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 + } }, - "id": { - "description": "Composite actor identifier. Format is `\"user-\"` for human users or `\"agent-\"` for agents.", - "example": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2", - "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 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 + } }, - "name": { - "description": "Display name of the actor shown in the UI. `null` if no name is set.", - "example": "Example Name", - "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" }, - "profile_picture": { - "description": "Profile picture for the actor. `null` if the actor has no profile picture.", - "example": { + "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", @@ -52551,120 +57290,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 + } }, - "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" + "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 + } }, - "height": { - "description": "Height of the image in pixels. `null` if not known.", - "example": 600, - "type": "integer" + "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" + } }, - "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" + }, + "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" }, - "mime_type": { - "description": "MIME type of the image, e.g. `\"image/png\"` or `\"image/jpeg\"`. `null` if not known.", - "example": "application/json", - "type": "string" + "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" + } }, - "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" + "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" + } }, - "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" }, @@ -52692,21 +57917,23 @@ "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_teams__team_tasks", + } + }, + "/api/v1/teams/{team}/tasks/metrics": { + "get": { + "description": "Returns task activity metrics scoped to one team (the Network in ArchAgents).\n`open` counts currently open or in-progress team tasks, `created` counts\ntasks inserted in the UTC-day window, and `completed` counts tasks whose\n`closed_at` falls in that window while still in a closed status. Hard-deleted\ntasks are absent from the projection and therefore omitted. The daily series\nis zero-filled across the requested window and includes reconstructed\nend-of-day `open` stock (from remaining projection rows' inserted_at/closed_at).\n\nAny authenticated team member may read this count-only Network summary.\nRequests from callers without team access return 404 so team existence is\nnot disclosed.\n", + "operationId": "get_api_v1_teams__team_tasks_metrics", "parameters": [ { - "description": "Team ID (`tem_...`). The task will be owned by this team.", + "description": "Team ID (`tem_...`) whose task metrics should be returned.", "example": "string", "in": "path", "name": "team", @@ -52714,230 +57941,202 @@ "schema": { "type": "string" } + }, + { + "description": "UTC-day window. One of 7, 30, 90, or 365; defaults to 30.", + "example": 1, + "in": "query", + "name": "days", + "required": false, + "schema": { + "type": "integer" + } } ], - "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" + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "description": "Network-scoped task activity metrics.", + "example": { + "completed": 1, + "created": 1, + "days": 1, + "end_at": "2024-01-01T00:00:00Z", + "open": 1, + "series": [ + {} ], - "thread": "thr_01j3k5m7n9p2r4s6t8v0w1x2" - }, - "user": "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" + "start_at": "2024-01-01T00:00:00Z" }, - "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": { + "completed": { + "example": 1, + "type": "integer" }, - "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" - }, + "created": { + "example": 1, + "type": "integer" + }, + "days": { + "example": 1, + "type": "integer" + }, + "end_at": { + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "type": "string" + }, + "open": { + "example": 1, + "type": "integer" + }, + "series": { + "description": "Zero-filled UTC-day buckets with `date`, end-of-day `open`, `created`, and `completed`.", + "example": [ + {} + ], + "items": { "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" - } + "type": "array" }, - "required": [ - "name" - ], - "type": "object" + "start_at": { + "example": "2024-01-01T00:00:00Z", + "format": "date-time", + "type": "string" + } }, - "user": { - "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", - "type": "string" - } - }, - "required": [ - "task" - ], - "type": "object" - } - } - }, - "required": true - }, - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Task" + "required": [ + "days", + "start_at", + "end_at", + "open", + "created", + "completed", + "series" + ], + "type": "object" } } }, - "description": "The newly created task." + "description": "Successful response" }, "401": { "description": "Unauthorized" }, - "404": { - "description": "Task owner not found" + "404": { + "description": "Team not found" + }, + "422": { + "description": "Invalid parameters" + } + }, + "summary": "Get task activity metrics for a team", + "x-auth": [ + "publishable_key", + "bearer" + ] + } + }, + "/api/v1/teams/{team}/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_teams__team_tasks_ready", + "parameters": [ + { + "description": "Team ID (`tem_...`) owning the tasks.", + "example": "string", + "in": "path", + "name": "team", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "User ID (`usr_...`) owning the tasks.", + "example": "string", + "in": "query", + "name": "user", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Optional organization context for privileged callers.", + "example": "string", + "in": "query", + "name": "org", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Include blocked and actively leased open tasks with exclusion reasons.", + "example": true, + "in": "query", + "name": "explain", + "required": false, + "schema": { + "type": "boolean" + } + }, + { + "description": "Only include tasks assigned to the authenticated user.", + "example": true, + "in": "query", + "name": "assigned_to_me", + "required": false, + "schema": { + "type": "boolean" + } + }, + { + "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/teams/{team}/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_teams__team_tasks_blocker_cycles", - "parameters": [ { - "description": "Team ID (`tem_...`) owning the tasks.", + "description": "Only include tasks whose source matches this object kind.", "example": "string", - "in": "path", - "name": "team", - "required": true, + "in": "query", + "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": "query", - "name": "user", + "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", @@ -52947,7 +58146,7 @@ } }, { - "description": "Opaque cursor returned by the preceding page.", + "description": "Opaque cursor returned by the previous page.", "example": "string", "in": "query", "name": "after_cursor", @@ -52962,14 +58161,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", @@ -52998,6 +58294,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -53027,6 +58324,9 @@ "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "priority": 2, "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", "status": "open", "subtasks_count": 1, "tags": [ @@ -53037,25 +58337,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", @@ -53084,6 +58469,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -53113,6 +58499,9 @@ "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "priority": 2, "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", "status": "open", "subtasks_count": 1, "tags": [ @@ -53122,128 +58511,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", @@ -53257,64 +58558,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", @@ -53328,229 +58754,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", @@ -53558,156 +58784,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" }, @@ -53720,6 +58950,7 @@ }, "required": [ "data", + "authoritative", "has_more" ], "type": "object" @@ -53735,123 +58966,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", - "x-auth": [ - "publishable_key", - "bearer" - ] - } - }, - "/api/v1/teams/{team}/tasks/metrics": { - "get": { - "description": "Returns task activity metrics scoped to one team (the Network in ArchAgents).\n`open` counts currently open or in-progress team tasks, `created` counts\ntasks inserted in the UTC-day window, and `completed` counts tasks whose\n`closed_at` falls in that window while still in a closed status. Hard-deleted\ntasks are absent from the projection and therefore omitted. The daily series\nis zero-filled across the requested window and includes reconstructed\nend-of-day `open` stock (from remaining projection rows' inserted_at/closed_at).\n\nAny authenticated team member may read this count-only Network summary.\nRequests from callers without team access return 404 so team existence is\nnot disclosed.\n", - "operationId": "get_api_v1_teams__team_tasks_metrics", - "parameters": [ - { - "description": "Team ID (`tem_...`) whose task metrics should be returned.", - "example": "string", - "in": "path", - "name": "team", - "required": true, - "schema": { - "type": "string" - } - }, - { - "description": "UTC-day window. One of 7, 30, 90, or 365; defaults to 30.", - "example": 1, - "in": "query", - "name": "days", - "required": false, - "schema": { - "type": "integer" - } - } - ], - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "description": "Network-scoped task activity metrics.", - "example": { - "completed": 1, - "created": 1, - "days": 1, - "end_at": "2024-01-01T00:00:00Z", - "open": 1, - "series": [ - {} - ], - "start_at": "2024-01-01T00:00:00Z" - }, - "properties": { - "completed": { - "example": 1, - "type": "integer" - }, - "created": { - "example": 1, - "type": "integer" - }, - "days": { - "example": 1, - "type": "integer" - }, - "end_at": { - "example": "2024-01-01T00:00:00Z", - "format": "date-time", - "type": "string" - }, - "open": { - "example": 1, - "type": "integer" - }, - "series": { - "description": "Zero-filled UTC-day buckets with `date`, end-of-day `open`, `created`, and `completed`.", - "example": [ - {} - ], - "items": { - "type": "object" - }, - "type": "array" - }, - "start_at": { - "example": "2024-01-01T00:00:00Z", - "format": "date-time", - "type": "string" - } - }, - "required": [ - "days", - "start_at", - "end_at", - "open", - "created", - "completed", - "series" - ], - "type": "object" - } - } - }, - "description": "Successful response" - }, - "401": { - "description": "Unauthorized" - }, - "404": { - "description": "Team not found" - }, - "422": { - "description": "Invalid parameters" - } - }, - "summary": "Get task activity metrics for a team", + "summary": "List an owner's ready tasks", "x-auth": [ "publishable_key", "bearer" @@ -53973,6 +59091,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, @@ -54033,6 +59191,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -54062,6 +59221,9 @@ "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "priority": 2, "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", "status": "open", "subtasks_count": 1, "tags": [ @@ -54117,6 +59279,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -54146,6 +59309,9 @@ "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "priority": 2, "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", "status": "open", "subtasks_count": 1, "tags": [ @@ -54188,6 +59354,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -54217,6 +59384,9 @@ "parent": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "priority": 2, "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", + "source_id": "string", + "source_scope": "string", + "source_type": "string", "status": "open", "subtasks_count": 1, "tags": [ @@ -54231,6 +59401,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": { @@ -54242,6 +59413,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": { @@ -54271,20 +59443,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": { @@ -54298,40 +59474,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" } }, @@ -54343,11 +59527,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": { @@ -54386,12 +59572,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": { @@ -54426,6 +59620,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": { @@ -54444,20 +59639,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": { @@ -54471,40 +59670,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" } }, @@ -54516,16 +59723,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": { @@ -54536,6 +59746,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": { @@ -54561,11 +59790,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": { @@ -54577,6 +59808,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" } }, @@ -54818,7 +60050,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "participant": [ @@ -54829,6 +60061,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 +60076,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -55044,7 +60282,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 +60447,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "participant": [ @@ -55220,6 +60458,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 +60473,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -55435,7 +60679,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 +60690,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 +60700,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 +60841,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "participant": [ @@ -55608,6 +60852,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 +60867,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -55823,9 +61073,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 +61083,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 +61105,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 +61120,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" }, @@ -55871,21 +61128,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 +61199,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 +61249,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 +61280,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 +61312,7 @@ "example": { "key": "value" }, + "nullable": true, "type": "object" }, "muted": { @@ -56014,6 +61323,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 +61461,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 +61496,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -56366,16 +61678,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 +61704,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 +61759,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 +61769,7 @@ "embedded" ], "example": "cli", + "nullable": true, "type": "string" }, "attachments": { @@ -56557,21 +61882,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 +61911,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 +61925,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 +61975,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 +62014,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 +62069,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 +62086,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 +62111,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 +62167,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 +62178,7 @@ "width": { "description": "Width of this variant in pixels. `null` if not recorded.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -56836,11 +62192,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 +62213,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 +62240,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 +62251,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 +62264,7 @@ "org": { "description": "ID of the organization that owns this message (`org_...`).", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "reactions": { @@ -56954,6 +62316,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 +62332,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 +62481,10 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, + "nullable": true, "type": "object" }, "root_message_id": { @@ -57130,27 +62496,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 +62703,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 +62718,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -57204,6 +62729,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 +62744,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" }, @@ -57221,21 +62752,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 +62823,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 +63097,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,7 +63245,7 @@ }, "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "template_upgrade_available": true, - "updated_at": "2024-01-01T00:00:00Z", + "updated_at": "string", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" }, "properties": { @@ -57702,6 +63279,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -57852,23 +63430,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 +63459,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 +63489,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 +63647,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 +63722,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 +63744,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 +63755,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 +63780,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 +63800,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 +63850,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 +63872,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 +63888,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 +63910,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 +63943,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 +63951,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -58365,12 +63976,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 +63998,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": { @@ -58414,6 +64028,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": { @@ -58439,6 +64054,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -58487,11 +64103,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 +64120,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 +64151,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 +64162,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 +64248,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 +64270,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 +64281,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 +64306,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 +64326,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 +64376,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 +64398,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 +64414,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 +64436,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 +64469,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 +64477,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -58858,12 +64502,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 +64524,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": { @@ -58907,6 +64554,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": { @@ -58932,6 +64580,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -58980,11 +64629,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 +64646,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 +64677,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 +64688,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 +64724,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 +64746,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 +64764,7 @@ "virtual_path": { "description": "Virtual filesystem path for this template config. `null` if not set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -59124,22 +64784,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 +64810,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 +64832,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 +64843,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": { @@ -59187,6 +64854,7 @@ "items": { "type": "object" }, + "nullable": true, "type": "array" }, "tags": { @@ -59203,32 +64871,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 +64971,7 @@ "description": "An example description.", "is_unlisted": true, "key": "string", + "kind": "personal", "members": [ { "id": "string", @@ -59336,6 +65009,7 @@ "description": "An example description.", "is_unlisted": true, "key": "string", + "kind": "personal", "members": [ { "id": "string", @@ -59380,6 +65054,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 +65150,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 +66411,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 +67339,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" } ] @@ -61796,7 +67486,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" } ] @@ -61805,16 +67495,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 +67646,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" } ], @@ -62060,7 +67753,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 +67912,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "root_message_id": "string", @@ -62227,7 +67920,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "properties": { @@ -62261,6 +67954,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -62442,16 +68136,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 +68162,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 +68217,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 +68227,7 @@ "embedded" ], "example": "cli", + "nullable": true, "type": "string" }, "attachments": { @@ -62633,21 +68340,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 +68369,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 +68383,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 +68433,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 +68472,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 +68527,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 +68544,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 +68569,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 +68625,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 +68636,7 @@ "width": { "description": "Width of this variant in pixels. `null` if not recorded.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -62912,11 +68650,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 +68671,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 +68698,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 +68709,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 +68722,7 @@ "org": { "description": "ID of the organization that owns this message (`org_...`).", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "reactions": { @@ -63030,6 +68774,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 +68790,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 +68939,10 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, + "nullable": true, "type": "object" }, "root_message_id": { @@ -63206,27 +68954,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 +69877,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 +69958,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 +69986,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 +70015,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 +70036,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 +70063,9 @@ }, "description": "Successful response" }, + "400": { + "description": "Invalid cursor" + }, "401": { "description": "Unauthorized" }, @@ -64287,7 +70195,11 @@ "summary": "Retrieve the current user", "x-auth": [ "publishable_key", - "bearer" + "bearer", + "device_flow" + ], + "x-required-scopes": [ + "profile" ] } }, @@ -64511,36 +70423,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 +70682,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 +70706,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 +70727,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 +70762,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 +70802,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 +71039,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 +71139,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 +71209,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -65390,6 +71239,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 +71258,12 @@ "properties": { "after_cursor": { "example": "string", + "nullable": true, "type": "string" }, "before_cursor": { "example": "string", + "nullable": true, "type": "string" }, "data": { @@ -65444,6 +71298,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -65473,6 +71328,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 +71373,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -65544,6 +71403,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 +71420,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 +71432,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 +71658,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 +71689,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 +71739,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 +72221,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 +72388,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 +73015,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 +73049,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 +73131,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 +73146,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 +73279,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -66273,6 +73309,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 +73322,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 +73454,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -66359,6 +73484,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 +73496,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 +73543,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 +73739,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 +73769,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 +73935,7 @@ }, "required": [ "data", + "authoritative", "has_more" ], "type": "object" @@ -66981,10 +73951,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 +74076,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 +74176,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -67195,6 +74206,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 +74264,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -67279,6 +74294,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 +74339,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -67350,6 +74369,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 +74386,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 +74398,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 +74428,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 +74459,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 +74512,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 +74557,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 +74605,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 +74624,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 +74655,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 +74708,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 +74731,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 +74775,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 +74793,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 +75082,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "participant": [ @@ -68009,6 +75093,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 +75108,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -68224,7 +75314,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 +75479,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "participant": [ @@ -68400,6 +75490,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 +75505,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -68615,7 +75711,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 +75722,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 +75732,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 +75873,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "participant": [ @@ -68788,6 +75884,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 +75899,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -69003,9 +76105,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 +76115,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 +76137,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 +76152,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" }, @@ -69051,21 +76160,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 +76231,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 +76281,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 +76312,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 +76344,7 @@ "example": { "key": "value" }, + "nullable": true, "type": "object" }, "muted": { @@ -69194,6 +76355,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 +76493,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 +76528,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -69546,16 +76710,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 +76736,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 +76791,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 +76801,7 @@ "embedded" ], "example": "cli", + "nullable": true, "type": "string" }, "attachments": { @@ -69737,21 +76914,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 +76943,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 +76957,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 +77007,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 +77046,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 +77101,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 +77118,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 +77143,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 +77199,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 +77210,7 @@ "width": { "description": "Width of this variant in pixels. `null` if not recorded.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -70016,11 +77224,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 +77245,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 +77272,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 +77283,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 +77296,7 @@ "org": { "description": "ID of the organization that owns this message (`org_...`).", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "reactions": { @@ -70134,6 +77348,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 +77364,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 +77513,10 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, + "nullable": true, "type": "object" }, "root_message_id": { @@ -70310,27 +77528,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 +77735,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 +77750,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -70384,6 +77761,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 +77776,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" }, @@ -70401,21 +77784,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 +77855,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 +78129,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,7 +78277,7 @@ }, "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "template_upgrade_available": true, - "updated_at": "2024-01-01T00:00:00Z", + "updated_at": "string", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" }, "properties": { @@ -70882,6 +78311,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -71032,23 +78462,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 +78491,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 +78521,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 +78679,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 +78754,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 +78776,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 +78787,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 +78812,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 +78832,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 +78882,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 +78904,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 +78920,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 +78942,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 +78975,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 +78983,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -71545,12 +79008,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 +79030,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": { @@ -71594,6 +79060,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": { @@ -71619,6 +79086,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -71667,11 +79135,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 +79152,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 +79183,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 +79194,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 +79280,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 +79302,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 +79313,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 +79338,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 +79358,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 +79408,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 +79430,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 +79446,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 +79468,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 +79501,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 +79509,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -72038,12 +79534,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 +79556,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": { @@ -72087,6 +79586,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": { @@ -72112,6 +79612,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -72160,11 +79661,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 +79678,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 +79709,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 +79720,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 +79756,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 +79778,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 +79796,7 @@ "virtual_path": { "description": "Virtual filesystem path for this template config. `null` if not set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -72304,22 +79816,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 +79842,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 +79864,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 +79875,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": { @@ -72367,6 +79886,7 @@ "items": { "type": "object" }, + "nullable": true, "type": "array" }, "tags": { @@ -72383,32 +79903,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 +80003,7 @@ "description": "An example description.", "is_unlisted": true, "key": "string", + "kind": "personal", "members": [ { "id": "string", @@ -72516,6 +80041,7 @@ "description": "An example description.", "is_unlisted": true, "key": "string", + "kind": "personal", "members": [ { "id": "string", @@ -72560,6 +80086,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 +80182,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 +80251,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 +80715,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 +80966,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 +81514,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 +81662,7 @@ }, "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "template_upgrade_available": true, - "updated_at": "2024-01-01T00:00:00Z", + "updated_at": "string", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" }, "properties": { @@ -73796,6 +81696,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -73946,23 +81847,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 +81876,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 +81906,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 +82064,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 +82139,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 +82161,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 +82172,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 +82197,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 +82217,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 +82267,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 +82289,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 +82305,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 +82327,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 +82360,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 +82368,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -74459,12 +82393,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 +82415,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": { @@ -74508,6 +82445,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": { @@ -74533,6 +82471,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -74581,11 +82520,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 +82537,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 +82568,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 +82579,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 +82665,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 +82687,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 +82698,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 +82723,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 +82743,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 +82793,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 +82815,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 +82831,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 +82853,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 +82886,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 +82894,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -74952,12 +82919,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 +82941,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": { @@ -75001,6 +82971,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": { @@ -75026,6 +82997,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -75074,11 +83046,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 +83063,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 +83094,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 +83105,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 +83141,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 +83163,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 +83181,7 @@ "virtual_path": { "description": "Virtual filesystem path for this template config. `null` if not set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -75218,22 +83201,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 +83341,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 +83356,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" }, @@ -75373,21 +83364,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 +83435,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" } }, @@ -75641,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": { @@ -75649,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": { @@ -75668,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" @@ -76171,6 +84289,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 +84304,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -76320,7 +84444,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" } ], @@ -76522,7 +84646,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "participant": [ @@ -76533,6 +84657,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 +84672,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -76748,7 +84878,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 +85082,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "participant": [ @@ -76963,6 +85093,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 +85108,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -77178,7 +85314,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 +85698,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 +85713,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -77711,7 +85853,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" } ], @@ -77913,7 +86055,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "participant": [ @@ -77924,6 +86066,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 +86081,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -78139,7 +86287,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 +86514,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -78516,23 +86665,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 +86694,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 +86724,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 +86882,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 +86957,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 +86979,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 +86990,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 +87015,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 +87035,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 +87085,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 +87107,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 +87123,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 +87145,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 +87178,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 +87186,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -79029,12 +87211,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 +87233,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": { @@ -79078,6 +87263,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": { @@ -79103,6 +87289,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -79151,11 +87338,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 +87355,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 +87386,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 +87397,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 +87483,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 +87505,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 +87516,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 +87541,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 +87561,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 +87611,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 +87633,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 +87649,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 +87671,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 +87704,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 +87712,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -79522,12 +87737,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 +87759,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": { @@ -79571,6 +87789,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": { @@ -79596,6 +87815,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -79644,11 +87864,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 +87881,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 +87912,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 +87923,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 +87959,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 +87981,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 +87999,7 @@ "virtual_path": { "description": "Virtual filesystem path for this template config. `null` if not set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -79788,22 +88019,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 +88246,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 +88261,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -80218,6 +88457,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 +88472,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -80447,6 +88692,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -80597,23 +88843,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 +88872,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 +88902,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 +89060,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 +89135,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 +89157,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 +89168,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 +89193,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 +89213,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 +89263,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 +89285,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 +89301,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 +89323,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 +89356,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 +89364,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -81110,12 +89389,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 +89411,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": { @@ -81159,6 +89441,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": { @@ -81184,6 +89467,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -81232,11 +89516,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 +89533,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 +89564,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 +89575,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 +89661,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 +89683,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 +89694,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 +89719,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 +89739,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 +89789,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 +89811,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 +89827,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 +89849,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 +89882,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 +89890,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -81603,12 +89915,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 +89937,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": { @@ -81652,6 +89967,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": { @@ -81677,6 +89993,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -81725,11 +90042,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 +90059,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 +90090,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 +90101,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 +90137,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 +90159,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 +90177,7 @@ "virtual_path": { "description": "Virtual filesystem path for this template config. `null` if not set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -81869,22 +90197,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 +90239,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 +90254,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" }, @@ -81926,21 +90262,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 +90333,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 +90522,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" } ], @@ -82247,7 +90629,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 +90788,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "root_message_id": "string", @@ -82414,7 +90796,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "properties": { @@ -82448,6 +90830,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -82629,16 +91012,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 +91038,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 +91093,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 +91103,7 @@ "embedded" ], "example": "cli", + "nullable": true, "type": "string" }, "attachments": { @@ -82820,21 +91216,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 +91245,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 +91259,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 +91309,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 +91348,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 +91403,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 +91420,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 +91445,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 +91501,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 +91512,7 @@ "width": { "description": "Width of this variant in pixels. `null` if not recorded.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -83099,11 +91526,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 +91547,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 +91574,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 +91585,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 +91598,7 @@ "org": { "description": "ID of the organization that owns this message (`org_...`).", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "reactions": { @@ -83217,6 +91650,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 +91666,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 +91815,10 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, + "nullable": true, "type": "object" }, "root_message_id": { @@ -83393,27 +91830,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 +92104,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -83665,6 +92256,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 +92268,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 +92279,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 +92297,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 +92479,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "participant": [ @@ -83893,6 +92490,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 +92505,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -84108,7 +92711,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 +92721,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 +92743,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 +92758,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" }, @@ -84156,21 +92766,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 +92837,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 +92887,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 +92918,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 +92950,7 @@ "example": { "key": "value" }, + "nullable": true, "type": "object" }, "muted": { @@ -84299,6 +92961,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 +93099,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 +93134,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -84651,16 +93316,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 +93342,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 +93397,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 +93407,7 @@ "embedded" ], "example": "cli", + "nullable": true, "type": "string" }, "attachments": { @@ -84842,21 +93520,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 +93549,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 +93563,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 +93613,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 +93652,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 +93707,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 +93724,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 +93749,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 +93805,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 +93816,7 @@ "width": { "description": "Width of this variant in pixels. `null` if not recorded.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -85121,11 +93830,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 +93851,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 +93878,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 +93889,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 +93902,7 @@ "org": { "description": "ID of the organization that owns this message (`org_...`).", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "reactions": { @@ -85239,6 +93954,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 +93970,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 +94119,10 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, + "nullable": true, "type": "object" }, "root_message_id": { @@ -85415,27 +94134,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 +94341,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 +94356,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -85489,6 +94367,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 +94382,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" }, @@ -85506,21 +94390,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 +94461,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 +94735,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,7 +94883,7 @@ }, "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "template_upgrade_available": true, - "updated_at": "2024-01-01T00:00:00Z", + "updated_at": "string", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" }, "properties": { @@ -85987,6 +94917,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -86137,23 +95068,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 +95097,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 +95127,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 +95285,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 +95360,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 +95382,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 +95393,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 +95418,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 +95438,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 +95488,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 +95510,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 +95526,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 +95548,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 +95581,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 +95589,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -86650,12 +95614,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 +95636,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": { @@ -86699,6 +95666,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": { @@ -86724,6 +95692,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -86772,11 +95741,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 +95758,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 +95789,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 +95800,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 +95886,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 +95908,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 +95919,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 +95944,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 +95964,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 +96014,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 +96036,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 +96052,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 +96074,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 +96107,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 +96115,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -87143,12 +96140,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 +96162,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": { @@ -87192,6 +96192,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": { @@ -87217,6 +96218,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -87265,11 +96267,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 +96284,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 +96315,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 +96326,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 +96362,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 +96384,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 +96402,7 @@ "virtual_path": { "description": "Virtual filesystem path for this template config. `null` if not set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -87409,22 +96422,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 +96448,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 +96470,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 +96481,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": { @@ -87472,6 +96492,7 @@ "items": { "type": "object" }, + "nullable": true, "type": "array" }, "tags": { @@ -87488,32 +96509,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 +96644,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -87770,6 +96796,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 +96808,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 +96819,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 +96837,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 +97019,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "participant": [ @@ -87998,6 +97030,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 +97045,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -88213,7 +97251,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 +97261,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 +97283,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 +97298,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" }, @@ -88261,21 +97306,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 +97377,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 +97427,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 +97458,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 +97490,7 @@ "example": { "key": "value" }, + "nullable": true, "type": "object" }, "muted": { @@ -88404,6 +97501,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 +97639,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 +97674,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -88756,16 +97856,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 +97882,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 +97937,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 +97947,7 @@ "embedded" ], "example": "cli", + "nullable": true, "type": "string" }, "attachments": { @@ -88947,21 +98060,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 +98089,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 +98103,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 +98153,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 +98192,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 +98247,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 +98264,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 +98289,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 +98345,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 +98356,7 @@ "width": { "description": "Width of this variant in pixels. `null` if not recorded.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -89226,11 +98370,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 +98391,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 +98418,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 +98429,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 +98442,7 @@ "org": { "description": "ID of the organization that owns this message (`org_...`).", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "reactions": { @@ -89344,6 +98494,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 +98510,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 +98659,10 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, + "nullable": true, "type": "object" }, "root_message_id": { @@ -89520,27 +98674,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 +98881,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 +98896,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -89594,6 +98907,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 +98922,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" }, @@ -89611,21 +98930,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 +99001,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 +99275,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,7 +99423,7 @@ }, "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "template_upgrade_available": true, - "updated_at": "2024-01-01T00:00:00Z", + "updated_at": "string", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" }, "properties": { @@ -90092,6 +99457,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -90242,23 +99608,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 +99637,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 +99667,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 +99825,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 +99900,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 +99922,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 +99933,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 +99958,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 +99978,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 +100028,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 +100050,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 +100066,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 +100088,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 +100121,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 +100129,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -90755,12 +100154,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 +100176,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": { @@ -90804,6 +100206,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": { @@ -90829,6 +100232,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -90877,11 +100281,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 +100298,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 +100329,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 +100340,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 +100426,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 +100448,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 +100459,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 +100484,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 +100504,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 +100554,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 +100576,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 +100592,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 +100614,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 +100647,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 +100655,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -91248,12 +100680,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 +100702,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": { @@ -91297,6 +100732,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": { @@ -91322,6 +100758,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -91370,11 +100807,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 +100824,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 +100855,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 +100866,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 +100902,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 +100924,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 +100942,7 @@ "virtual_path": { "description": "Virtual filesystem path for this template config. `null` if not set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -91514,22 +100962,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 +100988,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 +101010,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 +101021,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": { @@ -91577,6 +101032,7 @@ "items": { "type": "object" }, + "nullable": true, "type": "array" }, "tags": { @@ -91593,32 +101049,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 +101285,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" } ] @@ -91967,7 +101427,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" } ], @@ -92074,7 +101534,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 +101693,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "root_message_id": "string", @@ -92241,7 +101701,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "properties": { @@ -92275,6 +101735,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -92456,16 +101917,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 +101943,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 +101998,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 +102008,7 @@ "embedded" ], "example": "cli", + "nullable": true, "type": "string" }, "attachments": { @@ -92647,21 +102121,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 +102150,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 +102164,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 +102214,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 +102253,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 +102308,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 +102325,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 +102350,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 +102406,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 +102417,7 @@ "width": { "description": "Width of this variant in pixels. `null` if not recorded.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -92926,11 +102431,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 +102452,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 +102479,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 +102490,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 +102503,7 @@ "org": { "description": "ID of the organization that owns this message (`org_...`).", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "reactions": { @@ -93044,6 +102555,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 +102571,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 +102720,10 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, + "nullable": true, "type": "object" }, "root_message_id": { @@ -93220,27 +102735,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 +103341,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 +103356,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -93822,7 +103496,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" } ], @@ -94024,7 +103698,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "participant": [ @@ -94035,6 +103709,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 +103724,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -94250,7 +103930,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 +104315,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 +104330,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -94784,7 +104470,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" } ], @@ -94986,7 +104672,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "participant": [ @@ -94997,6 +104683,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 +104698,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -95212,7 +104904,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 +105131,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -95589,23 +105282,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 +105311,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 +105341,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 +105499,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 +105574,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 +105596,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 +105607,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 +105632,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 +105652,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 +105702,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 +105724,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 +105740,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 +105762,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 +105795,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 +105803,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -96102,12 +105828,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 +105850,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": { @@ -96151,6 +105880,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": { @@ -96176,6 +105906,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -96224,11 +105955,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 +105972,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 +106003,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 +106014,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 +106100,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 +106122,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 +106133,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 +106158,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 +106178,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 +106228,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 +106250,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 +106266,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 +106288,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 +106321,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 +106329,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -96595,12 +106354,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 +106376,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": { @@ -96644,6 +106406,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": { @@ -96669,6 +106432,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -96717,11 +106481,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 +106498,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 +106529,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 +106540,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 +106576,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 +106598,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 +106616,7 @@ "virtual_path": { "description": "Virtual filesystem path for this template config. `null` if not set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -96861,22 +106636,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 +106863,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 +106878,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -97291,6 +107074,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 +107089,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -97520,6 +107309,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -97670,23 +107460,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 +107489,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 +107519,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 +107677,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 +107752,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 +107774,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 +107785,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 +107810,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 +107830,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 +107880,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 +107902,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 +107918,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 +107940,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 +107973,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 +107981,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -98183,12 +108006,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 +108028,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": { @@ -98232,6 +108058,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": { @@ -98257,6 +108084,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -98305,11 +108133,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 +108150,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 +108181,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 +108192,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 +108278,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 +108300,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 +108311,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 +108336,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 +108356,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 +108406,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 +108428,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 +108444,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 +108466,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 +108499,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 +108507,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -98676,12 +108532,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 +108554,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": { @@ -98725,6 +108584,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": { @@ -98750,6 +108610,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -98798,11 +108659,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 +108676,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 +108707,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 +108718,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 +108754,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 +108776,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 +108794,7 @@ "virtual_path": { "description": "Virtual filesystem path for this template config. `null` if not set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -98942,22 +108814,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 +108856,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 +108871,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" }, @@ -98999,21 +108879,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 +108950,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 +109139,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" } ], @@ -99320,7 +109246,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 +109405,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "root_message_id": "string", @@ -99487,7 +109413,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "properties": { @@ -99521,6 +109447,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -99702,16 +109629,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 +109655,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 +109710,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 +109720,7 @@ "embedded" ], "example": "cli", + "nullable": true, "type": "string" }, "attachments": { @@ -99893,21 +109833,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 +109862,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 +109876,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 +109926,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 +109965,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 +110020,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 +110037,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 +110062,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 +110118,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 +110129,7 @@ "width": { "description": "Width of this variant in pixels. `null` if not recorded.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -100172,11 +110143,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 +110164,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 +110191,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 +110202,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 +110215,7 @@ "org": { "description": "ID of the organization that owns this message (`org_...`).", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "reactions": { @@ -100290,6 +110267,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 +110283,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 +110432,10 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, + "nullable": true, "type": "object" }, "root_message_id": { @@ -100466,27 +110447,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 +110721,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -100738,6 +110873,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 +110885,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 +110896,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 +110914,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 +111096,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "participant": [ @@ -100966,6 +111107,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 +111122,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -101181,7 +111328,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 +111338,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 +111360,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 +111375,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" }, @@ -101229,21 +111383,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 +111454,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 +111504,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 +111535,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 +111567,7 @@ "example": { "key": "value" }, + "nullable": true, "type": "object" }, "muted": { @@ -101372,6 +111578,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 +111716,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 +111751,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -101724,16 +111933,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 +111959,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 +112014,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 +112024,7 @@ "embedded" ], "example": "cli", + "nullable": true, "type": "string" }, "attachments": { @@ -101915,21 +112137,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 +112166,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 +112180,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 +112230,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 +112269,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 +112324,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 +112341,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 +112366,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 +112422,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 +112433,7 @@ "width": { "description": "Width of this variant in pixels. `null` if not recorded.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -102194,11 +112447,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 +112468,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 +112495,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 +112506,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 +112519,7 @@ "org": { "description": "ID of the organization that owns this message (`org_...`).", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "reactions": { @@ -102312,6 +112571,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 +112587,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 +112736,10 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, + "nullable": true, "type": "object" }, "root_message_id": { @@ -102488,27 +112751,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 +112958,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 +112973,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" } @@ -102562,6 +112984,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 +112999,7 @@ "org": "org_0aBcDeFgHiJkLmNoPqRsTu", "org_name": "Example Name", "org_role": "member", + "org_slug": "example-slug", "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu", "sandbox_name": "Example Name" }, @@ -102579,21 +113007,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 +113078,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 +113352,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,7 +113500,7 @@ }, "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "template_upgrade_available": true, - "updated_at": "2024-01-01T00:00:00Z", + "updated_at": "string", "user": "usr_0aBcDeFgHiJkLmNoPqRsTu" }, "properties": { @@ -103060,6 +113534,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -103210,23 +113685,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 +113714,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 +113744,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 +113902,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 +113977,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 +113999,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 +114010,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 +114035,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 +114055,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 +114105,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 +114127,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 +114143,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 +114165,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 +114198,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 +114206,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -103723,12 +114231,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 +114253,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": { @@ -103772,6 +114283,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": { @@ -103797,6 +114309,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -103845,11 +114358,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 +114375,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 +114406,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 +114417,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 +114503,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 +114525,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 +114536,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 +114561,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 +114581,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 +114631,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 +114653,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 +114669,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 +114691,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 +114724,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 +114732,7 @@ "discriminator": { "propertyName": "type" }, + "nullable": true, "oneOf": [ { "description": "AutomationTemplate-specific details exposed by a Solution template summary.", @@ -104216,12 +114757,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 +114779,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": { @@ -104265,6 +114809,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": { @@ -104290,6 +114835,7 @@ ], "type": "object" }, + "nullable": true, "type": "array" }, "prefills": { @@ -104338,11 +114884,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 +114901,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 +114932,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 +114943,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 +114979,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 +115001,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 +115019,7 @@ "virtual_path": { "description": "Virtual filesystem path for this template config. `null` if not set.", "example": "string", + "nullable": true, "type": "string" } }, @@ -104482,22 +115039,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 +115065,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 +115087,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 +115098,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": { @@ -104545,6 +115109,7 @@ "items": { "type": "object" }, + "nullable": true, "type": "array" }, "tags": { @@ -104561,32 +115126,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 +115367,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" } }, @@ -104938,7 +115507,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "properties": { @@ -104972,6 +115541,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -105153,16 +115723,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 +115749,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 +115804,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 +115814,7 @@ "embedded" ], "example": "cli", + "nullable": true, "type": "string" }, "attachments": { @@ -105344,21 +115927,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 +115956,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 +115970,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 +116020,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 +116059,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 +116114,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 +116131,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 +116156,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 +116212,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 +116223,7 @@ "width": { "description": "Width of this variant in pixels. `null` if not recorded.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -105623,11 +116237,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 +116258,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 +116285,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 +116296,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 +116309,7 @@ "org": { "description": "ID of the organization that owns this message (`org_...`).", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "reactions": { @@ -105741,6 +116361,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 +116377,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 +116526,10 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, + "nullable": true, "type": "object" }, "root_message_id": { @@ -105917,27 +116541,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 +116899,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" } }, @@ -106262,7 +117039,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "properties": { @@ -106296,6 +117073,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -106477,16 +117255,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 +117281,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 +117336,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 +117346,7 @@ "embedded" ], "example": "cli", + "nullable": true, "type": "string" }, "attachments": { @@ -106668,21 +117459,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 +117488,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 +117502,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 +117552,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 +117591,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 +117646,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 +117663,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 +117688,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 +117744,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 +117755,7 @@ "width": { "description": "Width of this variant in pixels. `null` if not recorded.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -106947,11 +117769,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 +117790,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 +117817,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 +117828,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 +117841,7 @@ "org": { "description": "ID of the organization that owns this message (`org_...`).", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "reactions": { @@ -107065,6 +117893,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 +117909,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 +118058,10 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, + "nullable": true, "type": "object" }, "root_message_id": { @@ -107241,27 +118073,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 +118551,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "thread_id": "string" @@ -107715,7 +118700,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "properties": { @@ -107749,6 +118734,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -107930,16 +118916,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 +118942,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 +118997,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 +119007,7 @@ "embedded" ], "example": "cli", + "nullable": true, "type": "string" }, "attachments": { @@ -108121,21 +119120,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 +119149,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 +119163,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 +119213,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 +119252,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 +119307,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 +119324,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 +119349,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 +119405,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 +119416,7 @@ "width": { "description": "Width of this variant in pixels. `null` if not recorded.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -108400,11 +119430,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 +119451,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 +119478,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 +119489,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 +119502,7 @@ "org": { "description": "ID of the organization that owns this message (`org_...`).", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "reactions": { @@ -108518,6 +119554,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 +119570,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 +119719,10 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, + "nullable": true, "type": "object" }, "root_message_id": { @@ -108694,27 +119734,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 +120070,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "thread_id": "string" @@ -109018,7 +120211,7 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, "properties": { @@ -109052,6 +120245,7 @@ } ] }, + "nullable": true, "properties": { "add": { "description": "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", @@ -109233,16 +120427,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 +120453,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 +120508,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 +120518,7 @@ "embedded" ], "example": "cli", + "nullable": true, "type": "string" }, "attachments": { @@ -109424,21 +120631,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 +120660,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 +120674,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 +120724,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 +120763,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 +120818,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 +120835,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 +120860,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 +120916,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 +120927,7 @@ "width": { "description": "Width of this variant in pixels. `null` if not recorded.", "example": 800, + "nullable": true, "type": "integer" } }, @@ -109703,11 +120941,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 +120962,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 +120989,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 +121000,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 +121013,7 @@ "org": { "description": "ID of the organization that owns this message (`org_...`).", "example": "org_0aBcDeFgHiJkLmNoPqRsTu", + "nullable": true, "type": "string" }, "reactions": { @@ -109821,6 +121065,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 +121081,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 +121230,10 @@ "team": "tem_0aBcDeFgHiJkLmNoPqRsTu", "thread": "string", "type": "note", - "user": "string", + "user": "usr_0aBcDeFgHiJkLmNoPqRsTu", "visibility": "default" }, + "nullable": true, "type": "object" }, "root_message_id": { @@ -109997,27 +121245,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 +121528,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 +121554,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 +122156,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -110773,6 +122186,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 +122233,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -110846,6 +122263,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 +122308,7 @@ }, "description": "An example description.", "due_date": "2024-01-01T00:00:00Z", + "epic": "string", "id": "tsk_0aBcDeFgHiJkLmNoPqRsTu", "is_blocked": true, "links": { @@ -110917,6 +122338,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 +122355,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 +122367,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 +122397,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 +122428,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 +122481,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 +122526,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 +122574,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 +122593,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 +122624,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 +122677,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 +122700,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 +122744,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 +122762,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..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: 47683c10bd61 +# Content hash: 45505bffc4df 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." @@ -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/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/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/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..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: dac7b47edeed +# Content hash: 7efd3b7c1931 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.", ) @@ -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..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: 17b38b7953d3 +# Content hash: 3816e2e1ff4d 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 @@ -535,14 +545,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 +606,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 +693,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( @@ -784,14 +794,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 +855,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 +940,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 +1009,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 +1076,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 +1126,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 +1172,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 +1390,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 +1436,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 +1643,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 +1689,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 +1764,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 +2177,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 +2223,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 +2522,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 +2530,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 +2548,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 +2603,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 +2671,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 +2699,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 +2745,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.", @@ -2538,14 +2907,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 +2971,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 +3061,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( @@ -2795,14 +3164,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 +3228,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 +3317,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 +3388,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 +3457,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 +3469,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 +3478,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 +3512,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.", ) @@ -3223,15 +3592,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 +4082,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 +4152,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 +4187,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 +4221,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 +4241,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 +4354,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 +4433,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 +4463,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 +4494,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 +5067,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 +5137,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 +5172,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 +5206,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 +5226,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 +5339,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 +5418,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 +5448,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 +5479,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..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: 9c4b1d511908 +# Content hash: dcaf6f16ffbe 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.", @@ -1467,14 +1824,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 +1888,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 +1978,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( @@ -1724,14 +2081,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 +2145,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 +2234,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 +2305,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 +2374,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 +2386,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 +2395,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 +2429,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.", ) @@ -2152,15 +2509,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 +2541,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 +2710,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 +2733,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 +2758,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 +2790,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 +2825,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 +2859,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 +2879,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 +2962,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 +3041,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 +3071,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 +3102,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 +3190,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 +3432,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 +3467,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 +3501,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 +3521,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 +3604,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 +3683,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 +3713,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 +3744,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 +3832,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/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", + } + ], ) 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()