--- title: "Get the full descriptor document (spec + status) for a catalog entity" method: GET path: "/api/rest/v1/catalog/{id}/descriptor" tags: ["Catalog"] --- # Get the full descriptor document (spec + status) for a catalog entity `GET /api/rest/v1/catalog/{id}/descriptor` ## Request - Base URL: `https://app.componecat.ai` - URL: `https://app.componecat.ai/api/rest/v1/catalog/{id}/descriptor` - Auth: none required Returns the entity in `componecat.yaml` descriptor form: `metadata` and `spec` (desired state, including interfaces and declared relationships) plus a read-only `status` block of system-observed state such as repository metadata and descriptor sync status. ## Path parameters - `id` string, uuid, required ## Response `200` OK - RestApiResponseOfDescriptorDocument: Standard REST API response envelope for a single resource. - `data` DescriptorDocument, required: Represents a parsed componecat.yaml descriptor file. Mirrors the YAML structure defined in the descriptor format specification. - `apiVersion` string, required: API version for schema evolution (e.g. "componecat/v1"). - `kind` string, required: The kind of catalog entity (e.g. Component, System, Resource). - `namespace` string, nullable: Optional top-level namespace field. When specified, takes precedence over metadata.namespace. When neither top-level nor metadata namespace is specified, the entity will have no namespace (null). Must be lowercase alphanumeric with hyphens, 1-100 characters. - `metadata` DescriptorMetadata, required: Metadata section of a descriptor document. - `name` string, required: Unique name/identifier for the entity within the organization. - `displayName` string, nullable: Optional human-readable display name. When omitted, the entity name is derived from the Name field (identifier). - `description` string, nullable: Human-readable description of the entity. - `owner` string, nullable: Team identifier that owns this entity. - `namespace` string, nullable: Logical grouping namespace for the entity (defaults to "default"). - `tags` string[], nullable: Free-form tags for categorization. - `lifecycle` string, nullable: Lifecycle stage (e.g. experimental, development, production, deprecated, retired). - `parent` string, nullable: Deprecated parent reference. No longer supported — use spec.relationships instead. This property exists only so the parser can detect and reject it with a helpful error. - `spec` DescriptorSpec: Specification section of a descriptor document. - `repository` string, nullable: Source code repository URL. Can be user-declared in YAML or discovered by the system. - `interfaces` DescriptorInterface[], nullable: Interfaces exposed by this entity (APIs, CLIs, UIs, MCP servers). - `name` string, required: Human-readable name for the interface. - `kind` string, nullable: The kind of interface: api, cli, ui, mcp (defaults to api). - `protocol` string, nullable: Protocol type (e.g. http, https, grpc, graphql). - `url` string, nullable: URL for the interface. - `healthCheckUrl` string, nullable: URL for health check monitoring. - `authMethod` string, nullable: Authentication method (e.g. none, apiKey, oauth2, mtls, jwt, custom). - `specUrl` string, nullable: URL to the API specification (OpenAPI, protobuf, etc.). - `rateLimit` string, nullable: Human-readable rate limiting description. - `visibility` string, nullable: Visibility level: private, internal, partner, public (defaults to internal). - `labels` string[], nullable: Free-form labels for categorization. - `executableName` string, nullable: The executable name for CLI interfaces (e.g. "kubectl"). - `installMethod` string, nullable: Installation method (e.g. npm, pip, brew, apt, winget, dockerImage, binary, custom). - `installCommand` string, nullable: Installation command (e.g. "npm install -g @scope/cli"). - `version` string, nullable: Version of the CLI tool. - `documentationUrl` string, nullable: URL to the tool's documentation. - `sourceUrl` string, nullable: URL to the tool's source code repository. - `transportType` string, nullable: Transport type for MCP interfaces: stdio, sse, streamableHttp. - `command` string, nullable: Command to execute for MCP Stdio transport. - `toolCount` union: Number of tools exposed by the MCP server. - integer - string, int32 - `resourceCount` union: Number of resources exposed by the MCP server. - integer - string, int32 - `sharePlatform` string, nullable: The platform hosting the data share (e.g. "Snowflake", "Databricks"). - `shareName` string, nullable: The platform-level identifier for the data share. - `shareScope` string, nullable: Whether the share targets internal consumers or the public marketplace. - `listingUrl` string, nullable: URL to the marketplace listing for this data share. - `registryType` string, nullable: The package ecosystem (e.g. nuget, npm, docker, pypi, maven, helm, terraform, cargo, go, custom). - `packageName` string, nullable: The registry-specific package identifier (e.g. "Newtonsoft.Json", "@anthropic-ai/sdk"). - `registryUrl` string, nullable: URL of the registry where the package is published. Optional for public registries. - `fields` object, nullable: Arbitrary key-value pairs stored in the entity's Fields JSONB column. The key "languages" is intercepted and stored in the typed Languages column instead of JSONB. - `docs` DescriptorDocs: Container for documentation sections and external links within a descriptor spec. - `sections` DescriptorDocSection[], nullable: Documentation sections with content (authored, git-sourced, or referenced via contentRef). - `title` string, required: Title of the documentation section. - `type` string, nullable: Section type (e.g. overview, architecture, runbook, custom). - `content` string, nullable: Markdown content for inline documentation. - `sourcePath` string, nullable: Git source path for git-sourced documentation sections. When present during ingestion, sets up git-sourced sync from the entity's repository. - `sourceRepository` string, nullable: Override source repository for git-sourced documentation. Defaults to the entity's own repository if not specified. - `sourceBranch` string, nullable: Branch to fetch git-sourced content from. Defaults to the repository's default branch if not specified. - `contentRef` string, nullable: MCP resource URI for reading this section's content (output only). - `links` DescriptorDocLink[], nullable: External documentation links (Confluence, Notion, GitHub, etc.). - `title` string, required: Title of the documentation link. - `url` string, required: URL of the external documentation. - `relationships` DescriptorRelationship[], nullable: Relationships declared by this entity (parent-of, depends-on, etc.). - `target` string, required: Target entity reference URI (e.g. "system://default/payments", "component://payments/payment-gateway"). - `kind` string, required: Relationship kind key (e.g. "parent-of", "depends-on"). Must match an existing RelationshipKindDefinition.Key. - `description` string, nullable: Optional description of this specific relationship. - `status` DescriptorStatus: System-derived observed state for a descriptor document. Mirrors Kubernetes-style status: never authored by users, only populated on retrieval. - `createdAt` string, date-time: When the entity was first created. - `updatedAt` string, date-time: When the entity was last updated. - `activityLogRef` string, nullable: MCP resource URI for reading the entity's full activity log as a single document (output only). Emitted when content is not dereferenced and at least one entry exists. - `activityLog` string, nullable: The entity's full activity log rendered inline as a single Markdown document (output only). Emitted in place of string? DescriptorStatus.ActivityLogRef when content is dereferenced. - `repository` DescriptorRepositoryStatus: Observed repository metadata from the linked Git provider. - `status` string, nullable: Current accessibility status of the linked repository. - `defaultBranch` string, nullable: Default branch of the repository (e.g. "main", "master"). - `metadataUpdatedAt` string, date-time, nullable: When repository metadata was last fetched from the provider. - `hasDescriptorFile` boolean: Whether the linked repository contains a componecat.yaml descriptor file. - `syncStatus` DescriptorSyncInfo: Descriptor sync state from the source repository. - `status` string, nullable: Current sync status (e.g. Synced, Error, Missing, None). - `lastCommitSha` string, nullable: Commit SHA from the last successful sync. - `syncedAt` string, date-time, nullable: When the descriptor was last synced from the source repository. - `source` string, nullable: The raw source repository and descriptor path from which the descriptor was synced, in the composed "owner/repo:path/to/componecat.yaml" format (e.g. "acme/payment-gateway:componecat.yaml"). Prefer string? DescriptorSyncInfo.Repository and string? DescriptorSyncInfo.DescriptorPath for the parsed components. - `repository` string, nullable: The repository portion of string? DescriptorSyncInfo.Source (e.g. "acme/payment-gateway"), parsed so clients don't have to split the delimiter themselves. Null when string? DescriptorSyncInfo.Source is null. - `descriptorPath` string, nullable: The descriptor file path portion of string? DescriptorSyncInfo.Source (e.g. "services/api/componecat.yaml"), parsed so clients don't have to split the delimiter themselves. Null when string? DescriptorSyncInfo.Source is null. - `error` string, nullable: Error message from the last sync attempt, if any. - `languages` string[], nullable: Programming languages detected from the repository (distinct from user-declared spec.fields.languages). - `readme` string, nullable: README content fetched from the repository. ## Other responses - `401`: Unauthorized - `403`: Forbidden - `404`: Not Found - `429`: Too Many Requests --- [API](https://skmtc.dev/componecat/apis/componecat-rest-api.md) · [All operations](https://skmtc.dev/componecat/apis/componecat-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/componecat/apis/componecat-rest-api/revisions/6c53d4984720?raw)