Read visible uses of a provider reference

Action: app_topolo_developers.placements.used_in.

Outcome

Read the bounded visible stored uses of one reference in the active organization across all pinned versions.

GET /api/developer-console/reference-usages

Audience and access

This public guide documents a customer-facing read of private organization placement data. Use a person session in the intended active organization with app_topolo_developers.connections:read. The current descriptor declares static authorization, allowedServices:[] and no principalAccess override; that metadata does not grant a service, API key or workspace bypass.

The handler derives organizationId from the verified user; none of these action inputs accepts an organizationId. Authentication delegates to native verifyRequest and resolves the Developers app identity. An API-key workspace header is passed to native Auth for validation, never treated locally as a grant. The placement access check calls listAccessibleWorkspaces with the original request and organization. Published recovery recommends a person session when Auth cannot answer workspace membership.

Consumer workspace access at read or higher is sufficient for these three stored reads. They do not check a current provider-workspace grant, provider resource permission, active connection, workspace link or reference declaration. Those additional checks belong to separately authorized placement creation/refresh/provider actions. A returned provider reference is not permission to fetch its target.

Selected placement handlers do not call resolveWorkspaceContext or create a developer profile, and contain no placement/store mutations. Native authentication/app identity/workspace helpers remain separate dependencies; this source packet does not certify them as globally zero-write or authorize cleanup of any profile/mirror. Do not infer rollback or delete state after an authentication failure.

Exact published input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "reference": {
      "type": "string",
      "minLength": 10,
      "maxLength": 700,
      "pattern": "^topolo:.*"
    }
  },
  "required": [
    "reference"
  ],
  "additionalProperties": false
}

Exact published output schema

{
  "type": "object",
  "required": [
    "success",
    "data"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "message": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "additionalProperties": true
    }
  },
  "additionalProperties": true
}

Current complete wire and read behavior

Actual selected success is HTTP200 with the complete envelope {success:true,message:"OK",data:{...}}. There is no top-level timestamp. The published outputSchema stays deliberately open; the field inventory below describes the current source mapper without replacing the native schema with an invented closed contract. OK is the exact English key developers.api.messages.ok, associated by the accepted connection3 packet at the same immutable revision; do not branch on localized message text.

Each PlacementRecord has id,organizationId,consumer:{appId,workspaceId,kind,id},slot,reference:{app,workspace,type,id,version?},referenceString,label,status,statusReason,lastCheckedAt,createdBy,createdAt,updatedAt,removedBy,removedAt. slot,label,statusReason,lastCheckedAt,removedBy,removedAt are nullable. reference.version is omitted for a null/falsy stored reference_version and otherwise Number-converted; it is not emitted as version:null. referenceString is formatReference(reference). Stored timestamps and nullable fields are mapped without freshness or date normalization. Malformed stored values are not revalidated by this mapper.

Status is the stored snapshot ready|changed|unavailable|removed|access_removed. ready is not current provider health or access proof; changed can describe a pinned-version mismatch from a previous check. lastCheckedAt may be null or old and is not restamped by these reads. statusReason is an arbitrary stored string or null, not a new closed reason enum. createdAt/updatedAt are stored lifecycle timestamps, not native provider observation generations.

The stored status removed can describe a still-live placement whose provider resource was previously missing. It is distinct from soft deletion: all returned rows have removedAt:null; rows with non-null removed_at are excluded. removedBy remains a nullable mapped stored field and must not be used alone to infer deletion.

These selected service paths read the control database and call Auth workspace lookup with the caller context. They do not call caller.readAction, a provider action, catalog hydration, entitlement fetch, action partitions, Notify or any placement mutation. defaultPlacementDeps constructs those available adapters, but these reads do not invoke them. Workspace promises are cached per app only within the created caller context; database rows and Auth responses are sequential, not a single cross-system transaction or a current provider check.

Error responses are {success:false,error:{message,code?,details?}}; absent code/details are omitted rather than forced null. Native metadata error codes are recovery guidance and do not guarantee that every shared authentication/permission exception includes that code: the outer ApiError path forwards optional code/details and unexpected failures return HTTP500 with a message only. Preserve actual status/code/details/request correlation rather than inventing a complete success or a missing code.

All examples are complete source-derived SYNTHETIC UNRUN carriers with fictional identifiers, users, labels and timestamps. No private/customer/provider resource was read. Only native action metadata was fetched. Matching sourceRevision identifies source applicability; deployed serving code, runtime behavior and UI adoption were not independently tested.

The only input is required reference:string, length10..700 with native ^topolo:.* pattern. It is then semantically parsed as topolo:<app>/<workspace>/<type>/<id>[@<version>]. An object reference is not accepted by this action schema even though the shared readReference helper also supports objects internally. A prefix-valid string can still produce invalid_reference. No consumer/org/workspace filter,cursor,limit or includeRemoved is accepted.

data is {reference:TopoloReference,referenceString:string,placements:PlacementRecord[],count:number}. The top-level reference and formatted string reflect the parsed requested reference, including its optional pinned version. Lookup matches organization plus reference app,workspace,type,id and intentionally ignores the version, returning any stored pinned version of that same target. Each row retains its own reference/version; do not replace it with the requested version.

The store selects only removed_at IS NULL, sorts consumer_app_id,consumer_workspace_id,consumer_kind,consumer_id,created_at,id and applies LIMIT500 before access filtering. The service then asks Auth for each distinct consumer app through the request-local cache and retains only rows whose consumer workspace appears in that answer.

Null/unavailable workspace answers and thrown lookup failures normalized to null cause affected rows to be silently omitted. This read does not use workspacesOf’s503 failure path. Unavailable Auth for all matched apps may therefore yield HTTP200,count0. There is no warning or omitted count. Absence or count<500 does not establish no other stored/visible usages: inaccessible rows, unavailable access answers and the pre-filter500 cap can all hide further results. A repeated read is a later snapshot, not stable pagination.

No current provider workspace grant or provider resource read is required to list the stored reference usages. An input reference is an identifier, not proof of ownership/access. Returned consumer references do not authorize provider fetches, refreshes, removal, grant changes or delivery. Semantic parse failure returns422 invalid_reference before the selected store query.

Errors and recovery

The following current metadata entries describe recovery. Raw shared authentication failures may omit their catalog code; preserve the actual response.

[
  {
    "status": 401,
    "code": "authentication_required",
    "recovery": "Authenticate again in the intended Topolo environment."
  },
  {
    "status": 403,
    "code": "permission_denied",
    "recovery": "Use a principal holding the Developers connections permission this action declares."
  },
  {
    "status": 403,
    "code": "organization_required",
    "recovery": "Select the organization whose connections you manage; connections always act for the active organization."
  },
  {
    "status": 422,
    "code": "invalid_input",
    "recovery": "Use canonical application ids (app_<owner>_<name>) and only the fields in inputSchema."
  },
  {
    "status": 422,
    "code": "invalid_reference",
    "recovery": "Pass topolo:<app>/<workspace>/<type>/<id>."
  }
]

No selected placement mutation to undo. Correct only invalid inputs; reauthenticate/select the intended organization or restore genuinely authorized consumer access through supported controls as appropriate. Preserve404 concealment,503 uncertainty and used_in silent omission. No automatic grant expansion, refresh/provider call, placement create/delete, source/runtime effect or profile cleanup follows from this guide.

Verification

• Verify parsed data.reference/referenceString against the original target and keep each returned row’s own pinned version.
• Require count===placements.length. Record that the source cap is applied before visibility filtering; do not certify total or absence from an empty/small result.
• Respect silent Auth omission and old/null snapshot fields; never interpret this collection as current provider availability or authority.

Complete synthetic UNRUN carriers

Complete visible usages across different pinned versions

COMPLETE SYNTHETIC UNRUN HTTP200. Input version9 is preserved at data.reference; stored usages retain versions2 and4 because lookup spans any version. Every mapped row field is present and every identifier is fictional.

Request input:

{
  "reference": "topolo:app_example_provider/ws_provider_example/example.item/item_example@9"
}

Complete response body:

{
  "success": true,
  "message": "OK",
  "data": {
    "reference": {
      "app": "app_example_provider",
      "workspace": "ws_provider_example",
      "type": "example.item",
      "id": "item_example",
      "version": 9
    },
    "referenceString": "topolo:app_example_provider/ws_provider_example/example.item/item_example@9",
    "placements": [
      {
        "id": "plc_docs-example-c",
        "organizationId": "org_docs_fixture",
        "consumer": {
          "appId": "app_example_consumer",
          "workspaceId": "ws_consumer_example",
          "kind": "example.page",
          "id": "page_example"
        },
        "slot": "content",
        "reference": {
          "app": "app_example_provider",
          "workspace": "ws_provider_example",
          "type": "example.item",
          "id": "item_example",
          "version": 2
        },
        "referenceString": "topolo:app_example_provider/ws_provider_example/example.item/item_example@2",
        "label": "Example item",
        "status": "changed",
        "statusReason": "provider version 3",
        "lastCheckedAt": "2026-10-20T10:00:00.000Z",
        "createdBy": "user_docs_fixture",
        "createdAt": "2026-10-20T10:00:00.000Z",
        "updatedAt": "2026-10-20T10:00:00.000Z",
        "removedBy": null,
        "removedAt": null
      },
      {
        "id": "plc_docs-example-d",
        "organizationId": "org_docs_fixture",
        "consumer": {
          "appId": "app_example_consumer",
          "workspaceId": "ws_consumer_example",
          "kind": "example.page",
          "id": "page_other"
        },
        "slot": null,
        "reference": {
          "app": "app_example_provider",
          "workspace": "ws_provider_example",
          "type": "example.item",
          "id": "item_example",
          "version": 4
        },
        "referenceString": "topolo:app_example_provider/ws_provider_example/example.item/item_example@4",
        "label": null,
        "status": "ready",
        "statusReason": null,
        "lastCheckedAt": "2026-10-20T10:00:00.000Z",
        "createdBy": "user_docs_fixture",
        "createdAt": "2026-10-20T10:00:00.000Z",
        "updatedAt": "2026-10-20T10:00:00.000Z",
        "removedBy": null,
        "removedAt": null
      }
    ],
    "count": 2
  }
}

count=placements.length counts only returned visible rows. Verify each original consumer/organization and keep its stored pinned version. This output does not establish a complete usage inventory or a live provider permission.

Prefix-valid reference fails semantic parsing

COMPLETE SYNTHETIC UNRUN HTTP422. The input meets the coarse string prefix/length schema but lacks the full reference components. The internal-helper message mentions an object form; this public action still accepts only its published string input.

Request input:

{
  "reference": "topolo:not-a-reference"
}

Complete response body:

{
  "success": false,
  "error": {
    "message": "reference must be topolo:<app>/<workspace>/<type>/<id>[@<version>] or { app, workspace, type, id, version? }",
    "code": "invalid_reference"
  }
}

RECOVERY UNRUN: correct the identifier from a genuine supported resource/placement read in the original context. For this fictional example the exact corrected input is {"reference":"topolo:app_example_provider/ws_provider_example/example.item/item_example@9"}. The complete success carrier above shows the possible wire only if those rows are actually returned. Do not guess private identifiers, change organization or call the provider to bypass parse/access behavior.

Provenance and changelog

Source applicability: TopoloDevelopers@7b89bd3b39092cdc29f87540847bf99a243f0a40. Current production descriptors for these three actions were read on2026-10-22 and still name this source revision. Handler/store/caller/native-auth boundaries were read as immutable Git objects; no mutable checkout body was used. The current checkout HEAD differs and is not treated as the serving revision. Exact English success copy OK reuses the accepted connection3 source association at the same revision.

2026-10-22: first placement3 paired human/typed source guide; added complete wire/nullability, consumer access and provider boundary, bounded query/visibility semantics, stale-state limits and synthetic success/refusal/recovery carriers. Source association does not prove served runtime or UI behavior.