> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.oryxa.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Collaborate on Work Using Synq AI-Assisted Team Workspaces

> Create Human-AI teams, assign tasks, and define which AI-proposed outputs need human approval before any changes take effect in Synq.

The Team Workspace is where humans and AI agents collaborate on structured work inside Synq. You organize collaborators into **Human-AI teams**, each with its own operating cadence and approval rules. Within each team you create **AI tasks** — units of work the AI picks up, processes, and returns proposed outputs for. When a task requires approval, it pauses at the `proposed` stage so a human can review the result before it is finalized. This model lets you automate high-frequency, low-risk operations while keeping a human in the loop for anything that changes sensitive data.

***

## Retrieve your workspace

Fetch all teams and tasks that belong to your tenant and organization in a single call.

```http theme={null}
GET /api/v1/team-workspace
Authorization: Bearer TOKEN
X-Tenant-ID: your-tenant-id
X-Org-ID: your-org-id
```

**Response**

```json theme={null}
{
  "teams": [
    {
      "id": "e3b0c442-98fc-1c14-9afb-f4c8996fb924",
      "name": "Inventory Ops",
      "description": "Handles restock recommendations and PO drafts",
      "status": "active",
      "cadence_minutes": 60,
      "approval_policy": { "required_role": "MANAGER" },
      "created_at": "2024-11-01T09:00:00Z",
      "updated_at": "2024-11-15T14:22:00Z"
    }
  ],
  "tasks": [
    {
      "id": "7d793037-a076-4e75-9b5b-7b8e17e4e2e5",
      "team_id": "e3b0c442-98fc-1c14-9afb-f4c8996fb924",
      "title": "Draft restock PO for SKU-9982",
      "status": "proposed",
      "priority": "HIGH",
      "input_context": { "sku": "SKU-9982", "current_stock": 4, "reorder_point": 20 },
      "proposed_output": { "po_quantity": 200, "supplier_id": "SUP-14" },
      "requires_approval": true,
      "due_at": "2024-11-20T17:00:00Z",
      "started_at": "2024-11-19T10:05:00Z",
      "completed_at": "",
      "created_at": "2024-11-19T09:00:00Z",
      "updated_at": "2024-11-19T10:05:00Z"
    }
  ]
}
```

<ResponseField name="teams" type="array">
  List of Human-AI teams scoped to your tenant and organization.
</ResponseField>

<ResponseField name="tasks" type="array">
  The 100 most recent AI tasks across all teams, ordered by creation date descending.
</ResponseField>

***

## Create a Human-AI team

Teams are the containers for collaborative work. Only users with the **Admin** or **Manager** role can create them.

```http theme={null}
POST /api/v1/team-workspace/teams
Authorization: Bearer TOKEN
X-Tenant-ID: your-tenant-id
X-Org-ID: your-org-id
Content-Type: application/json
```

<CodeGroup>
  ```json Request theme={null}
  {
    "name": "Inventory Ops",
    "description": "Handles restock recommendations and PO drafts",
    "cadence_minutes": 60,
    "approval_policy": {
      "required_role": "MANAGER"
    }
  }
  ```

  ```json Response (201 Created) theme={null}
  {
    "id": "e3b0c442-98fc-1c14-9afb-f4c8996fb924",
    "name": "Inventory Ops",
    "description": "Handles restock recommendations and PO drafts",
    "status": "active",
    "cadence_minutes": 60,
    "approval_policy": { "required_role": "MANAGER" },
    "created_at": "2024-11-01T09:00:00Z",
    "updated_at": "2024-11-01T09:00:00Z"
  }
  ```
</CodeGroup>

### Team request fields

<ParamField body="name" type="string" required>
  A short, human-readable label for the team. Must be non-empty.
</ParamField>

<ParamField body="description" type="string">
  An optional longer explanation of what this team handles.
</ParamField>

<ParamField body="cadence_minutes" type="integer">
  How often (in minutes) the team's AI agent runs its work cycle. Defaults to `30` if omitted or set to `0`.
</ParamField>

<ParamField body="approval_policy" type="object">
  A JSON object that defines who must approve proposed outputs from tasks in this team. The structure is flexible — for example, `{ "required_role": "MANAGER" }` requires a Manager-level user to sign off. Omit or pass `{}` for no policy enforcement at the team level.
</ParamField>

### Team response fields

<ResponseField name="id" type="string">UUID that uniquely identifies the team.</ResponseField>
<ResponseField name="name" type="string">The team's display name.</ResponseField>
<ResponseField name="description" type="string">Optional description of the team's purpose.</ResponseField>
<ResponseField name="status" type="string">Lifecycle status of the team. Starts as `active`.</ResponseField>
<ResponseField name="cadence_minutes" type="integer">How often the AI agent runs, in minutes.</ResponseField>
<ResponseField name="approval_policy" type="object">The approval rules attached to the team.</ResponseField>
<ResponseField name="created_at" type="string">ISO 8601 timestamp when the team was created.</ResponseField>
<ResponseField name="updated_at" type="string">ISO 8601 timestamp of the last update.</ResponseField>

***

## Create an AI task

Tasks are units of work you assign to a team's AI agent. Users with the **Admin**, **Manager**, or **Editor** role can create tasks.

```http theme={null}
POST /api/v1/team-workspace/tasks
Authorization: Bearer TOKEN
X-Tenant-ID: your-tenant-id
X-Org-ID: your-org-id
Content-Type: application/json
```

<CodeGroup>
  ```json Request theme={null}
  {
    "team_id": "e3b0c442-98fc-1c14-9afb-f4c8996fb924",
    "title": "Draft restock PO for SKU-9982",
    "priority": "HIGH",
    "input_context": {
      "sku": "SKU-9982",
      "current_stock": 4,
      "reorder_point": 20
    },
    "requires_approval": true,
    "due_at": "2024-11-20T17:00:00Z"
  }
  ```

  ```json Response (201 Created) theme={null}
  {
    "id": "7d793037-a076-4e75-9b5b-7b8e17e4e2e5",
    "team_id": "e3b0c442-98fc-1c14-9afb-f4c8996fb924",
    "title": "Draft restock PO for SKU-9982",
    "status": "pending",
    "priority": "HIGH",
    "input_context": { "sku": "SKU-9982", "current_stock": 4, "reorder_point": 20 },
    "proposed_output": null,
    "requires_approval": true,
    "due_at": "2024-11-20T17:00:00Z",
    "started_at": "",
    "completed_at": "",
    "created_at": "2024-11-19T09:00:00Z",
    "updated_at": "2024-11-19T09:00:00Z"
  }
  ```
</CodeGroup>

### Task request fields

<ParamField body="team_id" type="string" required>
  UUID of the team this task belongs to. Must reference a team within your tenant and organization.
</ParamField>

<ParamField body="title" type="string" required>
  A concise description of what the task involves. Must be non-empty.
</ParamField>

<ParamField body="priority" type="string">
  Task urgency level. Accepted values: `LOW`, `NORMAL`, `HIGH`, `CRITICAL`. Defaults to `NORMAL`.
</ParamField>

<ParamField body="input_context" type="object">
  A free-form JSON object that provides the AI agent with the data it needs to complete the task — for example, a SKU, a date range, or a customer ID. Defaults to `{}`.
</ParamField>

<ParamField body="requires_approval" type="boolean">
  When `true`, the task pauses at `proposed` status after the AI generates output, waiting for a human to approve or reject it before the result is applied.
</ParamField>

<ParamField body="due_at" type="string">
  Optional deadline for the task, in RFC 3339 format (e.g. `2024-11-20T17:00:00Z`).
</ParamField>

### Task response fields

<ResponseField name="id" type="string">UUID that uniquely identifies the task.</ResponseField>
<ResponseField name="team_id" type="string">UUID of the team the task belongs to.</ResponseField>
<ResponseField name="title" type="string">The task description.</ResponseField>
<ResponseField name="status" type="string">Current lifecycle status (see below).</ResponseField>
<ResponseField name="priority" type="string">Task urgency: `LOW`, `NORMAL`, `HIGH`, or `CRITICAL`.</ResponseField>
<ResponseField name="input_context" type="object">The data payload supplied when creating the task.</ResponseField>
<ResponseField name="proposed_output" type="object">The AI-generated result, populated once the agent completes its work.</ResponseField>
<ResponseField name="requires_approval" type="boolean">Whether human sign-off is required before the output is applied.</ResponseField>
<ResponseField name="due_at" type="string">Optional deadline in RFC 3339 format.</ResponseField>
<ResponseField name="started_at" type="string">Timestamp when the AI agent began processing, if started.</ResponseField>
<ResponseField name="completed_at" type="string">Timestamp when the task reached a terminal state, if completed.</ResponseField>
<ResponseField name="created_at" type="string">ISO 8601 timestamp when the task was created.</ResponseField>
<ResponseField name="updated_at" type="string">ISO 8601 timestamp of the last update to the task.</ResponseField>

***

## Task lifecycle

Every task moves through a defined set of statuses from creation to completion.

<Steps>
  <Step title="pending">
    The task has been created and is waiting for the AI agent to pick it up during the team's next cadence cycle.
  </Step>

  <Step title="in_progress">
    The AI agent has started working on the task. The `started_at` timestamp is set at this point.
  </Step>

  <Step title="proposed">
    The AI agent has finished and written its result to `proposed_output`. If `requires_approval` is `true`, the task waits here for a human reviewer to approve or reject the output before it takes effect.
  </Step>

  <Step title="completed">
    The task is done. If approval was required, it was granted. The `completed_at` timestamp is set.
  </Step>
</Steps>

<Note>
  A task with `requires_approval: false` skips the `proposed` stage and moves directly from `in_progress` to `completed` once the agent finishes.
</Note>

<Tip>
  Set `requires_approval: true` for any task whose output will modify existing records — such as placing purchase orders, adjusting inventory counts, or updating pricing. This gives your team a review checkpoint before changes are persisted and prevents unintended bulk updates.
</Tip>

***

## Approval policy reference

The `approval_policy` field on a team is a flexible JSON object. You define the structure that matches your internal workflow. A common pattern is role-based approval:

```json theme={null}
{
  "required_role": "MANAGER",
  "notify_on_proposal": true,
  "auto_approve_after_hours": 24
}
```

<Accordion title="approval_policy key conventions">
  | Key                        | Type    | Description                                                                             |
  | -------------------------- | ------- | --------------------------------------------------------------------------------------- |
  | `required_role`            | string  | Minimum role required to approve a proposed output (e.g. `MANAGER`, `ADMIN`).           |
  | `notify_on_proposal`       | boolean | Whether to send a notification when a task enters `proposed` status.                    |
  | `auto_approve_after_hours` | integer | Automatically approve the proposed output if no action is taken within this many hours. |

  These keys are illustrative — Synq stores the object as-is and your approval workflow layer enforces the policy.
</Accordion>