List workspace links

Read active-organization workspace-link records, their approvals and bounded filtering limits.

Action and scope

app_topolo_developers.workspace_links.list

GET /api/developer-console/workspace-links

Read-only selected link-list branch.

Before you start

Use the intended environment, authenticated identity and active organization. Discover actual link/pair identities; every worked value is fictional and every example is SYNTHETIC / UNRUN.

Use the current credential-scoped contract and any required transport resource binding separately from action input. No input field overrides the active organization.

Source and declared-action revision are 7b89bd3b39092cdc29f87540847bf99a243f0a40. The separate Docs payload-format schema revision9530cc90f2762ce1c59d63175ff37fb23a1b24ba is not the Developers source revision.

Declared permission: app_topolo_developers.connections:read. Read the actual link/pair and relevant access first.

This selected list is organization-scoped and does not filter rows by the caller’s workspace membership. It remains subject to outer authentication and the declared connections:read permission.

Input fields

The action input is closed. Path linkId and any supplied representation must agree; no organization override, idempotency key or expected version is accepted.

Behavior and response

Success uses {success:true,message:"OK",data:...}. A list has organizationId,links,count. A mutation has outcome and the complete link record; unlink also has accessRemoved. The declared data schema is open, and the complete source-qualified examples below retain every link-record field.

The selected list branch reads nonremoved workspace-link rows for the caller’s active organization. It applies optional exact consumerAppId,providerAppId,consumerWorkspaceId,providerWorkspaceId,status filters together; it does not perform per-workspace membership lookups.

Rows are ordered by consumer app,provider app,consumer workspace,provider workspace and capped at500 with no continuation cursor. count is the number returned. Returned rows include full side approvals, requester, timestamps and removal fields; removed rows are excluded.

A filtered empty result does not validate that an input app/workspace exists, establish global completeness or attribute an earlier mutation. Stored active state does not certify a usable app connection, provider authorization or placement validity.

Errors and recovery

HTTP 403 · organization_required — Select the intended active organization through supported context controls.

HTTP 422 · invalid_input — Use only the exact declared fields and canonical id syntax; preserve current path/body agreement.

Shared authentication, declared permission or framework failures may occur before these selected branches. Uncaught storage/concurrency failures can have a different carrier; preserve actual status/body and do not infer no effects from a failed response.

Worked examples — synthetic and unrun

List complete active and pending records

SOURCE-DERIVED SYNTHETIC UNRUN HTTP 200. Assume valid outer authentication, active org_docs_fixture and connections:read. The bounded SQL result contains these two nonremoved rows in its documented pair order. Membership of either workspace is not checked by this selected list branch.

Input:

{}

Complete response body:

{
  "success": true,
  "message": "OK",
  "data": {
    "organizationId": "org_docs_fixture",
    "links": [
      {
        "id": "wsl_00000000-0000-4000-8000-000000000001",
        "organizationId": "org_docs_fixture",
        "consumerAppId": "app_docs_consumer",
        "consumerWorkspaceId": "ws_consumer_fixture",
        "providerAppId": "app_docs_provider",
        "providerWorkspaceId": "ws_provider_fixture",
        "status": "active",
        "requestedBy": "user_fixture_requester",
        "requestedAt": "2026-10-23T00:00:00.000Z",
        "consumerApprovedBy": "user_fixture_consumer_admin",
        "consumerApprovedAt": "2026-10-23T00:00:00.000Z",
        "providerApprovedBy": "user_fixture_provider_admin",
        "providerApprovedAt": "2026-10-23T00:00:00.000Z",
        "removedBy": null,
        "removedAt": null,
        "createdAt": "2026-10-23T00:00:00.000Z",
        "updatedAt": "2026-10-23T00:00:00.000Z"
      },
      {
        "id": "wsl_00000000-0000-4000-8000-000000000002",
        "organizationId": "org_docs_fixture",
        "consumerAppId": "app_docs_consumer",
        "consumerWorkspaceId": "ws_consumer_fixture",
        "providerAppId": "app_docs_provider",
        "providerWorkspaceId": "ws_provider_fixture_b",
        "status": "needs_approval",
        "requestedBy": "user_fixture_requester",
        "requestedAt": "2026-10-23T00:00:00.000Z",
        "consumerApprovedBy": "user_fixture_consumer_admin",
        "consumerApprovedAt": "2026-10-23T00:00:00.000Z",
        "providerApprovedBy": null,
        "providerApprovedAt": null,
        "removedBy": null,
        "removedAt": null,
        "createdAt": "2026-10-23T00:00:00.000Z",
        "updatedAt": "2026-10-23T00:00:00.000Z"
      }
    ],
    "count": 2
  }
}

Read status and each approval separately. count is the returned length; this response does not grant access to either workspace or provider resource.

An exact pair filter returns no live link

SOURCE-DERIVED SYNTHETIC UNRUN HTTP 200. Assume no nonremoved row matches all four filters in the actor organization. The ids are fictional filters and do not establish that the apps/workspaces exist.

Input:

{
  "consumerAppId": "app_docs_consumer",
  "consumerWorkspaceId": "ws_consumer_fixture",
  "providerAppId": "app_docs_provider",
  "providerWorkspaceId": "ws_provider_fixture"
}

Complete response body:

{
  "success": true,
  "message": "OK",
  "data": {
    "organizationId": "org_docs_fixture",
    "links": [],
    "count": 0
  }
}

This says no live row matched that scoped query. It does not identify who removed a past row, certify an earlier write, or validate the supplied workspace identities.

No active organization

SOURCE-DERIVED SYNTHETIC UNRUN HTTP 403. Assume shared authentication returned no active organization. The handler refuses before list input dispatch or DB read.

Input:

{}

Complete response body:

{
  "success": false,
  "error": {
    "message": "An active organization is required to manage app connections",
    "code": "organization_required"
  }
}

Select the intended organization through supported context controls; the closed input contains no organization override.

Verify the result

Compare returned organizationId and every exact pair/id to the intended context. Inspect consumer/provider approvals and stored status separately.

Use all four retained pair filters for a bounded read-back where possible. A broad list may hit500; count is not an exhaustive organization total.

Reading stored links does not approve, activate, unlink or certify provider/workspace access.

Recovery boundary

This selected read has no link mutation to undo. Correct only invalid filters or restore the original authorized identity/context. No automatic link, approval, unlink or permission change follows from a list result.

Related actions

• app_topolo_developers.workspace_links.approve
• app_topolo_developers.workspace_links.unlink

Source provenance and limits

Reviewed immutable Developers 7b89bd3b39092cdc29f87540847bf99a243f0a40 (tree b3817ca104370c067b373f1f9899b57f8283d086), selected placement route/service/store, caller context, connection lookup, actor policy and HTTP envelope. The saved Developers descriptors also declare 7b89bd3b39092cdc29f87540847bf99a243f0a40. Docs native-format validation separately uses9530cc90f2762ce1c59d63175ff37fb23a1b24ba. Source/declaration agreement does not certify serving adoption, transactionality, a runtime business result or current provider authorization. All examples are source-derived synthetic and unrun; automatic Knowledge invocation during builds remains UNKNOWN.

Change log

• 2026-10-23: Initial documentation of workspace_links.list with exact state/access boundaries, complete synthetic unrun responses, verification and recovery limits. No application behavior change is asserted.