# REST API

> Call Oasis from your own code with a workspace API key.

Use the REST API when you want to call Oasis directly from a script, a backend, or CI. To give an AI assistant access instead, [connect it over MCP](https://docs.joinoasis.com/mcp).

## Create a key
Workspace owners and admins create keys in [Settings → API](https://joinoasis.com/settings/api). Add a label so you can tell keys apart later. The full key is shown once, so copy it into a secrets manager before you close the dialog. Revoke a key from the same page; requests that use it fail with 401 right away.

A key belongs to one workspace and acts as the person who created it, with owner access to that workspace. Anyone holding it can read and change everything in the workspace, so treat it like a password. Keys cannot create or revoke other keys.

## Authenticate
Send the key in the `X-API-Key` header. Every path below is relative to the base URL `https://api.joinoasis.com/api/v1`.

```bash
curl https://api.joinoasis.com/api/v1/me/organization \
  -H "X-API-Key: $OASIS_API_KEY"
```

The response includes `org_id`, your workspace ID. Workspace routes take it in the path.

## Errors
| Status | Meaning |
| --- | --- |
| 401 | The key is missing, mistyped, or revoked. |
| 403 | The key cannot do this, for example managing API keys. |
| 404 | The resource does not exist in this workspace. |
| 422 | The request body failed validation. The response lists each invalid field. |

## Workspace

### Get workspace

`GET /me/organization`

Read the workspace the key belongs to. Its `org_id` goes in every workspace path.

**Example**

```bash
curl -X GET "https://api.joinoasis.com/api/v1/me/organization" \
  -H "X-API-Key: $OASIS_API_KEY"
```

**Response** `200` · object

| Field | Type | Description |
| --- | --- | --- |
| `org_id` | uuid | Workspace ID. Use it in every workspace path. |
| `org_name` | string |  |
| `logo_url` | string |  |
| `is_personal` | boolean |  |
| `plan` | string |  |
| `created_at` | datetime |  |

## Agents

### List agents

`GET /organizations/{org_id}/agents`

List agents in the workspace.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_id` | path | string | Yes |  |
| `include_triggers` | query | boolean |  |  |

**Example**

```bash
curl -X GET "https://api.joinoasis.com/api/v1/organizations/$ORG_ID/agents" \
  -H "X-API-Key: $OASIS_API_KEY"
```

**Response** `200` · array of object

| Field | Type | Description |
| --- | --- | --- |
| `agent_id` | string |  |
| `kind` | string |  |
| `name` | string |  |
| `agent_role` | string |  |
| `description` | string | Short description shown with the agent. |
| `state` | `idle` \| `active` |  |
| `picture_url` | string |  |
| `color` | array of string |  |
| `composio_toolkits` | array of string | Apps the agent can use, by toolkit slug (for example `gmail`). |
| `composio_require_approval` | boolean |  |
| `created_by` | string |  |
| `created_at` | string |  |
| `updated_at` | string |  |
| `caller_permission` | string |  |

### Create an agent

`POST /organizations/{org_id}/agents`

Create an agent with a name, role and standing instructions.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_id` | path | string | Yes |  |

**Body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `connection_grants` | array of object |  | Connected app accounts the agent can use. |
| `connection_grants[].connection_id` | string | Yes |  |
| `connection_grants[].scope` | string |  | 'read' \| 'write' |
| `connection_grants[].auto_approve` | boolean |  |  |
| `name` | string | Yes | Display name for the agent |
| `agent_role` | string |  |  |
| `description` | string |  | Short description shown with the agent. |
| `system_prompt` | string |  |  |
| `response_style` | `default` \| `warm` \| `direct` \| `professional` \| `super_casual` |  |  |
| `picture_url` | string |  |  |
| `color` | array of string |  |  |
| `composio_toolkits` | array of string |  | Apps the agent can use, by toolkit slug (for example `gmail`). |
| `composio_require_approval` | boolean |  | If true, draft actions and ask for approval before executing |
| `composio_toolkit_approval_overrides` | object |  | Per-app override of `composio_require_approval`, keyed by toolkit slug. |
| `enable_memory_recall` | boolean |  | Let the agent use its memory. |

**Example**

```bash
curl -X POST "https://api.joinoasis.com/api/v1/organizations/$ORG_ID/agents" \
  -H "X-API-Key: $OASIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Scout","agent_role":"Research analyst","system_prompt":"Research what you are asked about and cite sources."}'
```

**Response** `201` · object

| Field | Type | Description |
| --- | --- | --- |
| `agent_id` | string |  |
| `user_id` | string |  |
| `org_id` | string |  |
| `name` | string |  |
| `agent_role` | string |  |
| `description` | string | Short description shown with the agent. |
| `state` | `idle` \| `active` |  |
| `picture_url` | string |  |
| `color` | array of string |  |
| `composio_toolkits` | array of string | Apps the agent can use, by toolkit slug (for example `gmail`). |
| `composio_require_approval` | boolean |  |
| `composio_toolkit_account_source` | object | Per-app account choice, keyed by toolkit slug: `shared` uses the accounts granted to the agent, `self` has each person use their own. Missing keys mean `shared`. |
| `created_at` | string |  |
| `updated_at` | string |  |
| `created_by` | string |  |
| `kind` | string |  |
| `caller_permission` | string |  |
| `budget_amount_usd` | number |  |
| `budget_period` | string |  |

### Get an agent

`GET /agents/{agent_id}`

Read an agent's instructions and settings.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `agent_id` | path | string | Yes |  |

**Example**

```bash
curl -X GET "https://api.joinoasis.com/api/v1/agents/$AGENT_ID" \
  -H "X-API-Key: $OASIS_API_KEY"
```

**Response** `200` · object

| Field | Type | Description |
| --- | --- | --- |
| `agent_id` | string |  |
| `user_id` | string |  |
| `org_id` | string |  |
| `name` | string |  |
| `agent_role` | string |  |
| `description` | string | Short description shown with the agent. |
| `state` | `idle` \| `active` |  |
| `picture_url` | string |  |
| `color` | array of string |  |
| `composio_toolkits` | array of string | Apps the agent can use, by toolkit slug (for example `gmail`). |
| `composio_require_approval` | boolean |  |
| `composio_toolkit_account_source` | object | Per-app account choice, keyed by toolkit slug: `shared` uses the accounts granted to the agent, `self` has each person use their own. Missing keys mean `shared`. |
| `created_at` | string |  |
| `updated_at` | string |  |
| `created_by` | string |  |
| `kind` | string |  |
| `caller_permission` | string |  |
| `budget_amount_usd` | number |  |
| `budget_period` | string |  |

### Update an agent

`PUT /agents/{agent_id}`

Change an agent. Send only the fields you want to change.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `agent_id` | path | string | Yes |  |

**Body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string |  |  |
| `agent_role` | string |  |  |
| `description` | string |  | Short description shown with the agent. |
| `system_prompt` | string |  |  |
| `response_style` | `default` \| `warm` \| `direct` \| `professional` \| `super_casual` |  |  |
| `picture_url` | string |  |  |
| `color` | array of string |  |  |
| `composio_toolkits` | array of string |  | Apps the agent can use, by toolkit slug (for example `gmail`). |
| `composio_require_approval` | boolean |  |  |
| `composio_toolkit_approval_overrides` | object |  | Per-app override of `composio_require_approval`, keyed by toolkit slug. |
| `composio_toolkit_account_source` | object |  | Per-app account choice, keyed by toolkit slug: `shared` uses the accounts granted to the agent, `self` has each person use their own. Missing keys mean `shared`. |
| `enable_memory_recall` | boolean |  | Let the agent use its memory. |
| `budget_amount_usd` | number |  | USD cap for the budget period; null = no cap |
| `budget_period` | string |  | 'daily' \| 'weekly' \| 'monthly'; null = no cap |

**Example**

```bash
curl -X PUT "https://api.joinoasis.com/api/v1/agents/$AGENT_ID" \
  -H "X-API-Key: $OASIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description":"Researches competitors every week."}'
```

**Response** `200` · object

| Field | Type | Description |
| --- | --- | --- |
| `agent_id` | string |  |
| `user_id` | string |  |
| `org_id` | string |  |
| `name` | string |  |
| `agent_role` | string |  |
| `description` | string | Short description shown with the agent. |
| `state` | `idle` \| `active` |  |
| `picture_url` | string |  |
| `color` | array of string |  |
| `composio_toolkits` | array of string | Apps the agent can use, by toolkit slug (for example `gmail`). |
| `composio_require_approval` | boolean |  |
| `composio_toolkit_account_source` | object | Per-app account choice, keyed by toolkit slug: `shared` uses the accounts granted to the agent, `self` has each person use their own. Missing keys mean `shared`. |
| `created_at` | string |  |
| `updated_at` | string |  |
| `created_by` | string |  |
| `kind` | string |  |
| `caller_permission` | string |  |
| `budget_amount_usd` | number |  |
| `budget_period` | string |  |

### Delete an agent

`DELETE /agents/{agent_id}`

Delete an agent. This cannot be undone.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `agent_id` | path | string | Yes |  |

**Example**

```bash
curl -X DELETE "https://api.joinoasis.com/api/v1/agents/$AGENT_ID" \
  -H "X-API-Key: $OASIS_API_KEY"
```

**Response** `204` · no content

## Tasks

### List tasks

`GET /organizations/{org_id}/tasks`

List tasks in the workspace. Filter with `status` and page with `limit` and `offset`.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_id` | path | uuid | Yes |  |
| `status` | query | `active` \| `paused` \| `running` \| `blocked` \| `completed` \| `incomplete` \| `cancelled` |  |  |
| `scope` | query | `all` \| `open` \| `closed` |  |  |
| `limit` | query | integer |  |  |
| `offset` | query | integer |  |  |

**Example**

```bash
curl -X GET "https://api.joinoasis.com/api/v1/organizations/$ORG_ID/tasks" \
  -H "X-API-Key: $OASIS_API_KEY"
```

**Response** `200` · array of object

| Field | Type | Description |
| --- | --- | --- |
| `id` | uuid |  |
| `org_id` | uuid |  |
| `title` | string |  |
| `objective` | string |  |
| `exit_criteria` | string |  |
| `due_at` | datetime |  |
| `status` | `active` \| `paused` \| `running` \| `blocked` \| `completed` \| `incomplete` \| `cancelled` |  |
| `created_by_user_id` | uuid |  |
| `created_at` | datetime |  |
| `updated_at` | datetime |  |
| `archived_at` | datetime |  |
| `steps` | array of object |  |
| `latest_run` | object |  |

### Create a task

`POST /organizations/{org_id}/tasks`

Create a task with an objective and at least one step.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_id` | path | uuid | Yes |  |

**Body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | string | Yes |  |
| `objective` | string | Yes |  |
| `exit_criteria` | string |  |  |
| `due_at` | datetime |  |  |
| `heartbeat_interval_minutes` | integer |  |  |
| `steps` | array of object | Yes |  |
| `steps[].id` | uuid |  |  |
| `steps[].position` | integer | Yes |  |
| `steps[].title` | string | Yes |  |
| `steps[].instruction` | string | Yes |  |
| `steps[].kind` | `agent_wake` \| `human_action` \| `work` | Yes |  |
| `steps[].depends_on_step_ids` | array of uuid |  |  |
| `steps[].assignees` | array of object |  |  |
| `steps[].assignee_agent_id` | uuid |  |  |
| `steps[].assignee_user_id` | uuid |  |  |
| `steps[].configuration` | object |  |  |

**Example**

```bash
curl -X POST "https://api.joinoasis.com/api/v1/organizations/$ORG_ID/tasks" \
  -H "X-API-Key: $OASIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Weekly competitor scan","objective":"Summarize what competitors shipped this week","steps":[{"position":0,"title":"Scan","instruction":"Check each competitor changelog","kind":"work"}]}'
```

**Response** `201` · object

| Field | Type | Description |
| --- | --- | --- |
| `task` | object | An organization-wide outcome that may be executed many times. |
| `steps` | array of object |  |
| `approvals` | array of object |  |
| `latest_run` | object |  |
| `can_edit` | boolean |  |

### Get a task

`GET /organizations/{org_id}/tasks/{task_id}`

Read a task with its steps.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_id` | path | uuid | Yes |  |
| `task_id` | path | uuid | Yes |  |

**Example**

```bash
curl -X GET "https://api.joinoasis.com/api/v1/organizations/$ORG_ID/tasks/$TASK_ID" \
  -H "X-API-Key: $OASIS_API_KEY"
```

**Response** `200` · object

| Field | Type | Description |
| --- | --- | --- |
| `task` | object | An organization-wide outcome that may be executed many times. |
| `steps` | array of object |  |
| `approvals` | array of object |  |
| `latest_run` | object |  |
| `can_edit` | boolean |  |

### Update a task

`PATCH /organizations/{org_id}/tasks/{task_id}`

Change a task. Send only the fields you want to change. `steps` replaces the whole plan, so send unchanged steps with their IDs.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_id` | path | uuid | Yes |  |
| `task_id` | path | uuid | Yes |  |

**Body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | string |  |  |
| `objective` | string |  |  |
| `exit_criteria` | string |  |  |
| `due_at` | datetime |  |  |
| `status` | `active` \| `paused` \| `running` \| `blocked` \| `completed` \| `incomplete` \| `cancelled` |  |  |
| `heartbeat_interval_minutes` | integer |  |  |
| `next_heartbeat_at` | datetime |  |  |
| `steps` | array of object |  |  |
| `steps[].id` | uuid |  |  |
| `steps[].position` | integer | Yes |  |
| `steps[].title` | string | Yes |  |
| `steps[].instruction` | string | Yes |  |
| `steps[].kind` | `agent_wake` \| `human_action` \| `work` | Yes |  |
| `steps[].depends_on_step_ids` | array of uuid |  |  |
| `steps[].assignees` | array of object |  |  |
| `steps[].assignee_agent_id` | uuid |  |  |
| `steps[].assignee_user_id` | uuid |  |  |
| `steps[].configuration` | object |  |  |

**Example**

```bash
curl -X PATCH "https://api.joinoasis.com/api/v1/organizations/$ORG_ID/tasks/$TASK_ID" \
  -H "X-API-Key: $OASIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Weekly competitor scan (EU)"}'
```

**Response** `200` · object

| Field | Type | Description |
| --- | --- | --- |
| `task` | object | An organization-wide outcome that may be executed many times. |
| `steps` | array of object |  |
| `approvals` | array of object |  |
| `latest_run` | object |  |
| `can_edit` | boolean |  |

### Archive a task

`DELETE /organizations/{org_id}/tasks/{task_id}`

Archive a task.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_id` | path | uuid | Yes |  |
| `task_id` | path | uuid | Yes |  |

**Example**

```bash
curl -X DELETE "https://api.joinoasis.com/api/v1/organizations/$ORG_ID/tasks/$TASK_ID" \
  -H "X-API-Key: $OASIS_API_KEY"
```

**Response** `204` · no content

## Workflows

### List workflows

`GET /organizations/{org_id}/schedules`

List workflows. Set `include_disabled` to include paused ones.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_id` | path | string | Yes |  |
| `include_disabled` | query | boolean |  |  |

**Example**

```bash
curl -X GET "https://api.joinoasis.com/api/v1/organizations/$ORG_ID/schedules" \
  -H "X-API-Key: $OASIS_API_KEY"
```

**Response** `200` · array of object

| Field | Type | Description |
| --- | --- | --- |
| `id` | string |  |
| `task_id` | string |  |
| `org_id` | string |  |
| `name` | string |  |
| `description` | string |  |
| `kind` | string | `time`, `event` or `manual`. |
| `trigger_type` | string | `cron`, `composio` (an app event) or `manual`. |
| `composio_trigger_slug` | string | App event that starts the workflow, for example `GMAIL_NEW_EMAIL`. |
| `composio_trigger_config` | object | Settings for that app event. |
| `composio_connected_account_id` | string | Connected account the event watches. Defaults to your account for that app. |
| `cron_expr` | string |  |
| `timezone` | string |  |
| `execute_at` | string |  |
| `enabled` | boolean |  |
| `seed_prompt` | string | Instructions for each run. |
| `agent_ids` | array of string | Agents that do the work. |
| `human_participant_ids` | array of string |  |
| `created_by` | string |  |
| `visibility` | string |  |
| `last_run_at` | string |  |
| `last_run_status` | string |  |
| `last_run_error` | string |  |
| `run_count` | integer |  |
| `created_at` | string |  |
| `updated_at` | string |  |
| `condition_rules` | array of object | Filters on the event payload. A run starts only when every rule matches. |
| `fire_cap_per_window` | integer |  |
| `fire_cap_window_seconds` | integer |  |
| `paused_reason` | string |  |

### Create a workflow

`POST /organizations/{org_id}/schedules`

Create a workflow with instructions, assigned agents and when it runs: `manual`, `cron` (recurring) or `composio` (on an app event). Use an IANA timezone with `cron_expr`. Automatic triggers are active once saved.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_id` | path | string | Yes |  |

**Body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string |  |  |
| `description` | string |  |  |
| `kind` | string |  | `time`, `event` or `manual`. |
| `trigger_type` | string |  | `cron`, `composio` (an app event) or `manual`. |
| `composio_trigger_slug` | string |  | App event that starts the workflow, for example `GMAIL_NEW_EMAIL`. |
| `composio_trigger_config` | object |  | Settings for that app event. |
| `composio_connected_account_id` | string |  | Connected account the event watches. Defaults to your account for that app. |
| `cron_expr` | string |  | Standard 5-field cron, e.g. '0 8 * * *' |
| `timezone` | string |  | IANA timezone name, e.g. 'America/New_York' |
| `execute_at` | string |  | ISO 8601 datetime for one-time runs |
| `seed_prompt` | string |  | Instructions for each run. |
| `agent_ids` | array of string |  | Agents that do the work. |
| `human_participant_ids` | array of string |  | Human participant UUIDs |
| `visibility` | string |  | 'private' (creator-only) or 'public' (visible to whole org) |
| `condition_rules` | array of object |  | Filters on the event payload. A run starts only when every rule matches. |
| `condition_rules[].rule_type` | string |  | Always `deterministic`. |
| `condition_rules[].field` | string | Yes | Dotted path into the event payload, e.g. 'from' or 'repository.full_name' |
| `condition_rules[].operator` | string | Yes | One of: equals, contains, starts_with, ends_with, regex, exists, gt, lt |
| `condition_rules[].value` | any |  | Value to compare against; ignored for 'exists' |
| `fire_cap_per_window` | integer |  | Per-schedule rate limit; null = uncapped |
| `fire_cap_window_seconds` | integer |  | Window for fire_cap_per_window |
| `generate_task_blueprint` | boolean |  | Draft the step plan from `seed_prompt` when the workflow is saved. |

**Example**

```bash
curl -X POST "https://api.joinoasis.com/api/v1/organizations/$ORG_ID/schedules" \
  -H "X-API-Key: $OASIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Morning digest","trigger_type":"cron","cron_expr":"0 9 * * 1-5","timezone":"America/New_York","seed_prompt":"Post a digest of the previous day.","agent_ids":["AGENT_ID"]}'
```

**Response** `201` · object

| Field | Type | Description |
| --- | --- | --- |
| `id` | string |  |
| `task_id` | string |  |
| `org_id` | string |  |
| `name` | string |  |
| `description` | string |  |
| `kind` | string | `time`, `event` or `manual`. |
| `trigger_type` | string | `cron`, `composio` (an app event) or `manual`. |
| `composio_trigger_slug` | string | App event that starts the workflow, for example `GMAIL_NEW_EMAIL`. |
| `composio_trigger_config` | object | Settings for that app event. |
| `composio_connected_account_id` | string | Connected account the event watches. Defaults to your account for that app. |
| `cron_expr` | string |  |
| `timezone` | string |  |
| `execute_at` | string |  |
| `enabled` | boolean |  |
| `seed_prompt` | string | Instructions for each run. |
| `agent_ids` | array of string | Agents that do the work. |
| `human_participant_ids` | array of string |  |
| `created_by` | string |  |
| `visibility` | string |  |
| `last_run_at` | string |  |
| `last_run_status` | string |  |
| `last_run_error` | string |  |
| `run_count` | integer |  |
| `created_at` | string |  |
| `updated_at` | string |  |
| `condition_rules` | array of object | Filters on the event payload. A run starts only when every rule matches. |
| `fire_cap_per_window` | integer |  |
| `fire_cap_window_seconds` | integer |  |
| `paused_reason` | string |  |

### Get a workflow

`GET /organizations/{org_id}/schedules/{schedule_id}`

Read a workflow's instructions, agents, timing and enabled state.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_id` | path | string | Yes |  |
| `schedule_id` | path | string | Yes |  |

**Example**

```bash
curl -X GET "https://api.joinoasis.com/api/v1/organizations/$ORG_ID/schedules/$SCHEDULE_ID" \
  -H "X-API-Key: $OASIS_API_KEY"
```

**Response** `200` · object

| Field | Type | Description |
| --- | --- | --- |
| `id` | string |  |
| `task_id` | string |  |
| `org_id` | string |  |
| `name` | string |  |
| `description` | string |  |
| `kind` | string | `time`, `event` or `manual`. |
| `trigger_type` | string | `cron`, `composio` (an app event) or `manual`. |
| `composio_trigger_slug` | string | App event that starts the workflow, for example `GMAIL_NEW_EMAIL`. |
| `composio_trigger_config` | object | Settings for that app event. |
| `composio_connected_account_id` | string | Connected account the event watches. Defaults to your account for that app. |
| `cron_expr` | string |  |
| `timezone` | string |  |
| `execute_at` | string |  |
| `enabled` | boolean |  |
| `seed_prompt` | string | Instructions for each run. |
| `agent_ids` | array of string | Agents that do the work. |
| `human_participant_ids` | array of string |  |
| `created_by` | string |  |
| `visibility` | string |  |
| `last_run_at` | string |  |
| `last_run_status` | string |  |
| `last_run_error` | string |  |
| `run_count` | integer |  |
| `created_at` | string |  |
| `updated_at` | string |  |
| `condition_rules` | array of object | Filters on the event payload. A run starts only when every rule matches. |
| `fire_cap_per_window` | integer |  |
| `fire_cap_window_seconds` | integer |  |
| `paused_reason` | string |  |

### Update a workflow

`PATCH /organizations/{org_id}/schedules/{schedule_id}`

Change a workflow. Set `enabled` to false to pause it and true to resume.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_id` | path | string | Yes |  |
| `schedule_id` | path | string | Yes |  |

**Body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string |  |  |
| `description` | string |  |  |
| `kind` | string |  | `time`, `event` or `manual`. |
| `trigger_type` | string |  | `cron`, `composio` (an app event) or `manual`. |
| `composio_trigger_slug` | string |  | App event that starts the workflow, for example `GMAIL_NEW_EMAIL`. |
| `composio_trigger_config` | object |  | Settings for that app event. |
| `composio_connected_account_id` | string |  | Connected account the event watches. Defaults to your account for that app. |
| `cron_expr` | string |  |  |
| `timezone` | string |  |  |
| `execute_at` | string |  |  |
| `enabled` | boolean |  |  |
| `seed_prompt` | string |  | Instructions for each run. |
| `agent_ids` | array of string |  | Agents that do the work. |
| `human_participant_ids` | array of string |  |  |
| `visibility` | string |  |  |
| `condition_rules` | array of object |  | Filters on the event payload. A run starts only when every rule matches. |
| `condition_rules[].rule_type` | string |  | Always `deterministic`. |
| `condition_rules[].field` | string | Yes | Dotted path into the event payload, e.g. 'from' or 'repository.full_name' |
| `condition_rules[].operator` | string | Yes | One of: equals, contains, starts_with, ends_with, regex, exists, gt, lt |
| `condition_rules[].value` | any |  | Value to compare against; ignored for 'exists' |
| `fire_cap_per_window` | integer |  |  |
| `fire_cap_window_seconds` | integer |  |  |

**Example**

```bash
curl -X PATCH "https://api.joinoasis.com/api/v1/organizations/$ORG_ID/schedules/$SCHEDULE_ID" \
  -H "X-API-Key: $OASIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":false}'
```

**Response** `200` · object

| Field | Type | Description |
| --- | --- | --- |
| `id` | string |  |
| `task_id` | string |  |
| `org_id` | string |  |
| `name` | string |  |
| `description` | string |  |
| `kind` | string | `time`, `event` or `manual`. |
| `trigger_type` | string | `cron`, `composio` (an app event) or `manual`. |
| `composio_trigger_slug` | string | App event that starts the workflow, for example `GMAIL_NEW_EMAIL`. |
| `composio_trigger_config` | object | Settings for that app event. |
| `composio_connected_account_id` | string | Connected account the event watches. Defaults to your account for that app. |
| `cron_expr` | string |  |
| `timezone` | string |  |
| `execute_at` | string |  |
| `enabled` | boolean |  |
| `seed_prompt` | string | Instructions for each run. |
| `agent_ids` | array of string | Agents that do the work. |
| `human_participant_ids` | array of string |  |
| `created_by` | string |  |
| `visibility` | string |  |
| `last_run_at` | string |  |
| `last_run_status` | string |  |
| `last_run_error` | string |  |
| `run_count` | integer |  |
| `created_at` | string |  |
| `updated_at` | string |  |
| `condition_rules` | array of object | Filters on the event payload. A run starts only when every rule matches. |
| `fire_cap_per_window` | integer |  |
| `fire_cap_window_seconds` | integer |  |
| `paused_reason` | string |  |

### Delete a workflow

`DELETE /organizations/{org_id}/schedules/{schedule_id}`

Delete a workflow and its trigger. Past runs and their results may remain.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_id` | path | string | Yes |  |
| `schedule_id` | path | string | Yes |  |

**Example**

```bash
curl -X DELETE "https://api.joinoasis.com/api/v1/organizations/$ORG_ID/schedules/$SCHEDULE_ID" \
  -H "X-API-Key: $OASIS_API_KEY"
```

**Response** `204` · no content

## Rooms

### List rooms

`GET /organizations/{org_id}/rooms`

List rooms you can see in the workspace.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_id` | path | string | Yes |  |
| `include_archived` | query | boolean |  |  |
| `include_cli` | query | boolean |  |  |
| `workspace_view` | query | boolean |  |  |
| `limit` | query | integer |  |  |
| `before` | query | string |  |  |
| `room_ids` | query | array of uuid |  |  |

**Example**

```bash
curl -X GET "https://api.joinoasis.com/api/v1/organizations/$ORG_ID/rooms" \
  -H "X-API-Key: $OASIS_API_KEY"
```

**Response** `200` · array of object

| Field | Type | Description |
| --- | --- | --- |
| `id` | uuid |  |
| `org_id` | uuid |  |
| `name` | string |  |
| `description` | string |  |
| `picture_url` | string |  |
| `agent_participants` | array of uuid |  |
| `human_participants` | array of uuid |  |
| `archived` | boolean |  |
| `pinned` | boolean |  |
| `room_type` | string |  |
| `visibility` | string |  |
| `created_by` | uuid |  |
| `created_at` | string |  |
| `updated_at` | string |  |
| `unread` | boolean |  |
| `unread_count` | integer |  |
| `latest_message_preview` | string |  |
| `messages` | object |  |

### Create a room

`POST /organizations/{org_id}/rooms`

Create a room. Add agents with `agent_participants`.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_id` | path | string | Yes |  |

**Body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes |  |
| `description` | string |  |  |
| `agent_participants` | array of uuid |  |  |
| `human_participants` | array of uuid |  |  |
| `room_type` | `room` \| `agent_draft` \| `cli` |  |  |
| `visibility` | `public` \| `private` |  |  |

**Example**

```bash
curl -X POST "https://api.joinoasis.com/api/v1/organizations/$ORG_ID/rooms" \
  -H "X-API-Key: $OASIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Nightly report","visibility":"private"}'
```

**Response** `201` · object

| Field | Type | Description |
| --- | --- | --- |
| `id` | uuid |  |
| `org_id` | uuid |  |
| `name` | string |  |
| `description` | string |  |
| `picture_url` | string |  |
| `agent_participants` | array of uuid |  |
| `human_participants` | array of uuid |  |
| `archived` | boolean |  |
| `pinned` | boolean |  |
| `room_type` | string |  |
| `visibility` | string |  |
| `created_by` | uuid |  |
| `created_at` | string |  |
| `updated_at` | string |  |
| `unread` | boolean |  |
| `unread_count` | integer |  |
| `latest_message_preview` | string |  |
| `messages` | object |  |

### Delete a room

`DELETE /rooms/{room_id}`

Delete a room and its messages.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `room_id` | path | string | Yes |  |

**Example**

```bash
curl -X DELETE "https://api.joinoasis.com/api/v1/rooms/$ROOM_ID" \
  -H "X-API-Key: $OASIS_API_KEY"
```

**Response** `204` · no content

## Messages

### List messages

`GET /rooms/{room_id}/messages`

Read a room's messages. Page with `limit` and `before`.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `room_id` | path | string | Yes |  |
| `limit` | query | integer |  |  |
| `before` | query | string |  |  |

**Example**

```bash
curl -X GET "https://api.joinoasis.com/api/v1/rooms/$ROOM_ID/messages" \
  -H "X-API-Key: $OASIS_API_KEY"
```

**Response** `200` · object

| Field | Type | Description |
| --- | --- | --- |
| `messages` | array of object |  |
| `has_more` | boolean |  |
| `oldest_cursor` | string |  |
| `newest_cursor` | string |  |

### Send a message

`POST /rooms/{room_id}/messages`

Post a message as the key's creator. Put an agent's ID in `mentions` to wake it. Reuse `idempotency_key` when retrying so the message is not posted twice.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `room_id` | path | string | Yes |  |

**Body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `content` | string | Yes |  |
| `attachments` | array of object |  |  |
| `extras` | object |  |  |
| `mentions` | array of uuid |  | IDs of the agents or people mentioned. Mentioned agents in the room start working on the message. |
| `idempotency_key` | string |  | Retrying with the same key returns the original message instead of posting it again. |
| `thread_root_message_id` | uuid |  | Top-level message this reply belongs to. |
| `reply_to_message_id` | uuid |  | Main-timeline message quoted by this inline reply. |
| `also_show_in_main` | boolean |  | Also show this thread reply in the room's main timeline. |

**Example**

```bash
curl -X POST "https://api.joinoasis.com/api/v1/rooms/$ROOM_ID/messages" \
  -H "X-API-Key: $OASIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"Summarize the signups from yesterday","idempotency_key":"report-2026-10-12"}'
```

**Response** `201` · object

| Field | Type | Description |
| --- | --- | --- |
| `id` | uuid |  |
| `room_id` | uuid |  |
| `sender_type` | string |  |
| `content` | string |  |
| `mentions` | array of uuid | IDs of the agents or people mentioned. Mentioned agents in the room start working on the message. |
| `message_type` | string |  |
| `idempotency_key` | string | Retrying with the same key returns the original message instead of posting it again. |
| `attachments` | array of object |  |
| `thread_root_message_id` | uuid |  |
| `reply_to_message_id` | uuid |  |
| `also_show_in_main` | boolean | Also show this thread reply in the room's main timeline. |
| `sent_at` | string |  |
| `reply_count` | integer |  |
| `reactions` | array of object |  |

## Members

### List members

`GET /organizations/{org_id}/members`

List the people in the workspace and their roles.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_id` | path | string | Yes |  |

**Example**

```bash
curl -X GET "https://api.joinoasis.com/api/v1/organizations/$ORG_ID/members" \
  -H "X-API-Key: $OASIS_API_KEY"
```

**Response** `200` · array of object

| Field | Type | Description |
| --- | --- | --- |
| `id` | string |  |
| `user_id` | string |  |
| `org_id` | string |  |
| `role` | string |  |
| `email` | string |  |
| `name` | string |  |
| `created_at` | string |  |
| `picture_url` | string |  |

## Approvals

### List approvals

`GET /organizations/{org_id}/pending-approvals`

List actions waiting for someone to approve or reject them.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_id` | path | string | Yes |  |
| `status` | query | string |  |  |
| `execution_state` | query | string |  |  |
| `limit` | query | integer |  |  |
| `action_kind` | query | string |  |  |

**Example**

```bash
curl -X GET "https://api.joinoasis.com/api/v1/organizations/$ORG_ID/pending-approvals" \
  -H "X-API-Key: $OASIS_API_KEY"
```

**Response** `200` · array of object

| Field | Type | Description |
| --- | --- | --- |
| `id` | uuid |  |
| `status` | string | `pending`, `approved` or `rejected`. |
| `agentId` | uuid | Agent that wants to act. |
| `agentName` | string |  |
| `toolkit` | string | App the action runs in, for example `gmail`. |
| `actionName` | string |  |
| `actionDescription` | string |  |
| `toolArgs` | object | Arguments the agent wants to run the action with. |
| `roomId` | uuid |  |
| `taskId` | uuid |  |
| `approverUserIds` | array of uuid | People who can approve or reject it. |
| `createdAt` | datetime |  |
| `resolvedAt` | datetime |  |
| `resolvedBy` | uuid |  |
| `rejectionReason` | string |  |