Skip to content

Get Component Registry Summary

Method

This API follows the REST methodology.

HTTP Method

GET: Read a summary of the project's component registry โ€” what a component sweep actually landed.

This is the plugin's "What's in the registry" panel, and the way to confirm a component upload or resync worked.

Naming Convention

The response is proxied verbatim from the internal wf2des-api data plane, so its fields are snake_case.

Request and Response

Headers

Request Headers

  • Authorization
  • Accept
  • Accept-language

Response Headers

  • Content-Type

Get Registry Summary

URI

GET /api/v1/organizations/{organization_id}/projects/{project_id}/wf2des/registry

Path Parameters

Name Type Required Description
organization_id integer Required Organization ID
project_id integer Required Project ID

Response

The response is JSON (HTTP status: 200 OK).

{
  "total": 279,
  "published": 173,
  "local": 106,
  "names": ["Button", "Card", "Checkbox", "Divider", "Footer-SP"]
}

Response Fields

Name Type Description
total integer How many components the registry holds for this project.
published integer How many are kind: "published" โ€” components carrying a publish key, which the plugin can instantiate.
local integer total - published. Local components, including keyless twins the REST sweep landed.
names string[] A bounded, alphabetically sorted sample of component names โ€” at most 50, not the full list.

Reading the split

published vs local is the useful signal, not total. A component with no publish key cannot be materialized by the plugin at all, so a large local count means the registry looks fuller than it usefully is.

That gap is expected right after a component upload: the REST sweep cannot read inside a design-system library, so it lands keyless local twins. Submitting component captures is what converts them โ€” the captures are authoritative for component_key, so published rises and local falls without total necessarily changing.

Why there is no per-board breakdown

A design_component document records the component's own node, not the board it was swept from, so a per-board count is not derivable here. The project-wide total, the published/local split and a bounded name sample are what the registry can actually answer.

Authentication

Authentication is performed using JSON Web Tokens (JWT) issued by Amazon Cognito. The caller must additionally hold access to the project.

Error Handling

Description Status Code Status Name
Missing authentication credentials 401 Unauthorized
Insufficient permissions 403 Forbidden
Project or organization not found 404 Not Found
Upstream read failure (wf2des-api) 500 Internal Server Error

An empty registry returns 200 with total: 0, not 404.

Processing Flow

  1. Extract organization ID and project ID from path parameters.
  2. Verify the user has access to the project.
  3. Proxy the read to the internal wf2des-api data plane (X-AI-Service-Token), scoped to the organization and project.
  4. The data plane counts the project's design_component documents, counts the published subset, and reads up to 50 names sorted alphabetically.
  5. Return the summary verbatim.