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

# WorkspaceProvider

> WorkspaceProvider is the join table that records which global Provider entries a specific workspace has explicitly selected and/or was auto-matched to, acting a

WorkspaceProvider is the join table that records which global Provider entries a specific workspace has explicitly selected and/or was auto-matched to, acting as the per-tenant provider bookmark layer. Each row links exactly one Workspace to one Provider and carries two boolean flags — `is_selected` (user explicitly added the provider via the API) and `is_matched` (system or explicit selection confirmed the relevance). The entity is owned by the `WorkspaceProviderService`, which upserts rows on explicit selection and soft-deletes them on removal. It is the authority for `GET /v1/workspaces/:id/providers` catalog responses and is read by the Vision Agent to resolve per-workspace provider scope.

| Naming                          | Value                             |
| ------------------------------- | --------------------------------- |
| Object                          | WorkspaceProvider                 |
| Resource type (JSON:API `type`) | `workspace_provider`              |
| Collection / records root       | — <sub>(not a records root)</sub> |
| REST base                       | `/v1/workspace-providers`         |
| Entity class                    | `WorkspaceProvider`               |

<Note>
  **Internal object.** Not currently exposed on the public REST API. The operations below describe the intended contract.
</Note>

## API operations

| Operation | Method & path                         | Status     |
| --------- | ------------------------------------- | ---------- |
| List      | `GET /v1/workspace-providers`         | 🟡 Planned |
| Retrieve  | `GET /v1/workspace-providers/{id}`    | 🟡 Planned |
| Create    | `POST /v1/workspace-providers`        | 🟡 Planned |
| Update    | `PATCH /v1/workspace-providers/{id}`  | 🟡 Planned |
| Delete    | `DELETE /v1/workspace-providers/{id}` | 🟡 Planned |

## Data model

### Attributes

| Field        | Type                    | Required | Constraints                                                                                                                             | Allowed values                                     | Description                                                                                                                                                                                                     |
| ------------ | ----------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| is\_selected | boolean                 | ⚪ No     | DEFAULT false                                                                                                                           | true, false                                        | Whether the workspace has explicitly selected this provider through the UI or API. Set to true via POST /v1/workspaces/:id/providers; set to false implicitly on soft-delete.                                   |
| is\_matched  | boolean                 | ⚪ No     | DEFAULT false; set to true automatically whenever is\_selected is set to true (repository enforces: if isSelected → is\_matched = true) | true, false                                        | Whether the provider was confirmed relevant to this workspace, either through explicit user selection (which auto-sets this flag) or via system matching logic such as the workspace-provider scoring pipeline. |
| created\_at  | 🔒 system — timestamptz | ⚪ No     | onCreate hook; DEFAULT now()                                                                                                            | —                                                  | Timestamp of row creation. Set automatically by MikroORM onCreate hook.                                                                                                                                         |
| updated\_at  | 🔒 system — timestamptz | ⚪ No     | onCreate + onUpdate hooks                                                                                                               | —                                                  | Timestamp of last row modification. Refreshed automatically by MikroORM onUpdate hook.                                                                                                                          |
| deleted\_at  | timestamptz \| null     | ⚪ No     | nullable; set to current timestamp on soft-delete via WorkspaceProviderRepository.softDelete                                            | null (active) or ISO 8601 timestamp (soft-deleted) | Soft-delete marker. When non-null the provider is considered deselected for the workspace. All active-provider queries filter deleted\_at IS NULL.                                                              |

### Relationships

| Name      | Type               | Required | Description                                                                                                                                                                             |
| --------- | ------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| workspace | to-one (ManyToOne) | ✅ Yes    | The workspace that selected this provider. Foreign key workspace\_pk → core\_api.workspaces.pk. Every WorkspaceProvider row is strictly tenant-scoped to this workspace.                |
| provider  | to-one (ManyToOne) | ✅ Yes    | The global provider catalog entry being bookmarked. Foreign key provider\_pk → core\_api.providers.pk. Carries provider name, slug, category, logo, URL, and Vision Agent skill fields. |

### System-computed

* pk — auto-increment integer primary key; internal only, never exposed in the API
* created\_at — set by MikroORM onCreate: () => new Date() hook
* updated\_at — set by both onCreate and onUpdate: () => new Date() hooks
* deleted\_at — null at creation; stamped with current timestamp by WorkspaceProviderRepository.softDelete() when the user removes the provider via DELETE /v1/workspaces/:id/providers/:providerId
* is\_matched — automatically forced to true by the repository upsert logic whenever is\_selected is set to true (business rule: explicit user selection always counts as matched)
* is\_selected default — false at row creation; set to true by WorkspaceProviderService.createWorkspaceProvider() via WorkspaceProviderRepository.upsert(workspace, provider, true)

## Example

```json theme={null}
{
  "data": {
    "type": "workspace_provider",
    "id": "a3f1c2d4-88e0-4b5a-9f3c-1d2e3f4a5b6c",
    "attributes": {
      "is_selected": true,
      "is_matched": true,
      "created_at": "2025-11-14T09:30:00.000Z",
      "updated_at": "2025-11-14T09:30:00.000Z",
      "deleted_at": null
    },
    "relationships": {
      "workspace": {
        "data": { "type": "workspace", "id": "d7e8f9a0-1234-4abc-8def-0123456789ab" }
      },
      "provider": {
        "data": { "type": "provider", "id": "b2c3d4e5-5678-4bcd-9ef0-1234567890bc" }
      }
    }
  }
}
```

<sub>Source: `apps/api/src/database/entities/WorkspaceProvider.ts` · domain: ingestion · tier: Platform</sub>