Provider

Provider is the Well platform’s catalog entry for every external service or application that a workspace can connect to or interact with via the Well extension. Each Provider record carries identity metadata (name, slug, URL, logo), geographic availability, category classification, and an optional Vision Agent skill (a SKILL.md payload that the AI navigator uses at runtime). Providers are global platform records — not scoped to a specific workspace — and are managed exclusively by the platform via seed scripts and the Vision Agent pipeline. Workspaces link to providers through the workspace_providers join entity, and connectors are associated with providers through the provider_connectors junction table.

Naming	Value
Object	Provider
Resource type (JSON:API `type`)	`provider`
Collection / records root	— _{(not a records root)}
REST base	`/v1/providers`
Entity class	`Provider`

Internal object. Not currently exposed on the public REST API. The operations below describe the intended contract.

API operations

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

Data model

Attributes

Field	Type	Required	Constraints	Allowed values	Description
provider_id	string (UUID)	✅ Yes	Unique; default gen_random_uuid()	—	Public immutable identifier for the provider. Generated server-side on creation.
name	string	✅ Yes	NOT NULL	—	Human-readable display name of the provider (e.g. ‘Qonto’, ‘Stripe’).
slug	string	✅ Yes	Unique; indexed	—	URL-safe identifier used as the stable key for provider lookups and MCP routing. Unique across all providers.
blueprint_json	json (nullable)	⚪ No	Nullable	—	Live blueprint payload — the executable flow JSON consumed by the Well browser extension. Populated by ContributionService.publishBlueprint or the one-shot backfill script. Null when no blueprint has been contributed.
url	string (varchar 255)	✅ Yes	Max length 255	—	Canonical homepage or login URL for the provider. Used as the entry point for Vision Agent navigation.
countries	string[] (array, nullable)	⚪ No	Nullable; stored as Postgres array	—	ISO-3166-1 alpha-2 country codes indicating geographic availability of the provider. Null means globally available or availability unknown.
category	🔒 system — enum (ProviderCategoryEnum, native type provider_category_enum)	✅ Yes	Default: ‘General’; NOT NULL; native Postgres enum	Finance \| Accounting \| Productivity \| CRM & Marketing \| Dev & Infra \| Telecom \| Travel & Logistics \| E-commerce & Retail \| Media & Subscriptions \| General	Thematic grouping shown in the connector onboarding UI. Stored as the enum VALUE string (e.g. ‘Finance’, not ‘FINANCE’). Defaults to ‘General’.
searchable_terms	string[] (array, nullable)	⚪ No	Nullable; stored as Postgres array	—	Additional keywords indexed for fuzzy search in the provider catalog. Supplements the name and slug for discovery.
popularity_score	integer (nullable)	⚪ No	Nullable. Referenced by composite partial index idx_providers_active_skill_planner for ordered planner reads.	—	Relative popularity rank used to sort providers in the catalog and prioritize the Vision Agent planner’s skill selection. Higher is more popular. Managed by the platform scoring pipeline.
skill	text (nullable)	⚪ No	Nullable. Added by Migration20260520161351.	—	Full SKILL.md content consumed by the Vision Agent at runtime — YAML frontmatter followed by markdown step body. Null when no skill exists; Vision Agent falls back to pure-vision mode. Written by the Vision Agent skill pipeline (Autobrowse or human contribution).
skill_metadata	jsonb (nullable)	⚪ No	Nullable. Shape: ProviderSkillMetadata (name, description, version, source, confidence_score, last_success_at?, last_run_at?, triggers?, successful_uses?, total_uses?, pending_revision?). Added by Migration20260520161351.	—	Parsed SKILL.md frontmatter augmented with runtime execution statistics. Updated atomically by the Vision Agent runner after every run. Contains the optional pending_revision sub-object when a re-synthesized skill is awaiting human review.
skill_status	🔒 system — enum (ProviderSkillStatusEnum, native type provider_skill_status_enum)	✅ Yes	Default: ‘none’; NOT NULL; native Postgres enum. Covered by composite partial index idx_providers_active_skill_planner (WHERE deleted_at IS NULL AND skill_status <> ‘none’). Added by Migration20260520161351.	none \| draft \| yellow \| green \| drifting \| broken	Lifecycle status of the Vision Agent skill. Transitions: none→draft (Autobrowse generate), draft→yellow (successfulUses ≥ 2 AND EWMA ≥ 0.7), yellow→green (EWMA ≥ 0.85), green→drifting (EWMA < 0.7), drifting→broken (score < 0.3), drifting→green (regen). Broken→* requires human or Autobrowse regen.
skill_version	integer	✅ Yes	Default: 0; NOT NULL. Added by Migration20260520161351.	—	Monotonic version counter incremented on every skill regeneration. Used by the pending_revision mechanism to compute the target version stamp at synthesis time.
created_at	🔒 system — timestamptz	✅ Yes	Default: now(); NOT NULL	—	Timestamp of record creation. Set by the database default on insert; never updated.
updated_at	🔒 system — timestamptz	✅ Yes	Default: now(); onUpdate hook sets to current timestamp	—	Timestamp of last modification. Automatically maintained by MikroORM onUpdate hook on every entity flush.
deleted_at	🔒 system — timestamptz (nullable)	⚪ No	Nullable; null = active record	—	Soft-delete timestamp. Non-null means the provider has been logically deleted and is excluded from the active planner index (idx_providers_active_skill_planner WHERE deleted_at IS NULL).

Relationships

Name	Type	Required	Description
logo	to-one (Media)	No	Optional brand logo asset. References core_api.media. Nullable ManyToOne — providers without a logo have null here. The Media entity holds GCS storage metadata.
workspace_providers	to-many (WorkspaceProvider)	No	Collection of workspace-to-provider link records (core_api.workspace_providers). Each entry represents a specific workspace that has activated or pinned this provider. Inverse side of WorkspaceProvider.provider.
connectors	to-many (ProviderConnector)	No	Collection of connector associations via the provider_connectors junction table. Each ProviderConnector links this provider to a specific Connector (MCP or native). Inverse side of ProviderConnector.provider. Cascade-deleted when the provider is hard-deleted.

System-computed

provider_id — generated server-side via gen_random_uuid() database default on INSERT; never accepted from client input
created_at — set to now() by database default on INSERT; never modified
updated_at — automatically set to now() by MikroORM onUpdate hook on every entity flush
deleted_at — set by soft-delete logic in the service layer; null on all active records; excluded from the active skill planner index
skill_status — state-machine transitions driven exclusively by VisionAgentSkillService.nextStatus(); values advance from none→draft→yellow→green based on EWMA confidence scoring and successfulUses counter; never set by user input
skill_version — monotonically incremented by the skill pipeline on every regeneration cycle; initial default 0 set by migration
skill_metadata.successful_uses / total_uses — incremented atomically by the Vision Agent executor after each run; JSONB field so updates do not bump the row version for ORM change detection
skill_metadata.pending_revision — populated by the incremental re-synthesis loop when an active YELLOW or GREEN skill has a candidate replacement awaiting human review; cleared on promotion or rejection
popularity_score — maintained by the platform scoring pipeline (Migration20260417100000_provider_scoring_task_layer); not computed on-the-fly per request
category — seeded and bulk-updated by migrations (Migration20260413200000_expand_provider_categories); entity initializer default is ‘General’
blueprint_json — populated by ContributionService.publishBlueprint or one-shot backfill scripts; not user-editable via public API

Example

{
  "data": {
    "id": "a3f7c921-8b4e-4d1c-9ef2-d35a70bc1234",
    "type": "provider",
    "attributes": {
      "name": "Qonto",
      "slug": "qonto",
      "url": "https://qonto.com",
      "category": "Finance",
      "countries": ["FR", "DE", "IT", "ES"],
      "searchable_terms": ["bank", "neobank", "compte pro", "fintech"],
      "popularity_score": 980,
      "blueprint_json": null,
      "skill": "---\nname: Qonto\ndescription: Log in and sync your Qonto account\nversion: 2\n---\n# Steps\n...",
      "skill_status": "green",
      "skill_version": 2,
      "skill_metadata": {
        "name": "Qonto",
        "description": "Log in and sync your Qonto account",
        "version": 2,
        "source": "autobrowse",
        "confidence_score": 0.91,
        "last_success_at": "2026-05-28T14:22:00Z",
        "last_run_at": "2026-05-28T14:22:00Z",
        "successful_uses": 47,
        "total_uses": 51,
        "triggers": ["connect bank account"]
      },
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2026-05-28T14:22:00Z",
      "deleted_at": null
    },
    "relationships": {
      "logo": {
        "data": { "id": "media-uuid-here", "type": "media" }
      }
    }
  }
}

_{Source: /Users/maximechampoux/platform/apps/api/src/database/entities/Provider.ts · domain: ingestion · tier: Platform}

Main objects

Supporting objects

Platform objects

Activity objects

Infrastructure objects

API operations

Data model

Attributes

Relationships

System-computed

Example

​API operations

​Data model

​Attributes

​Relationships

​System-computed

​Example

API operations

Data model

Attributes

Relationships

System-computed

Example