---
title: "Load one saved package metadata record for the signed-in user, including community-fork source listing provenance, th..."
method: GET
path: "/v1/packages/{package_id}"
tags: ["packages"]
---

# Load one saved package metadata record for the signed-in user, including community-fork source listing provenance, th...

`GET /v1/packages/{package_id}`

## Request

- Base URL: `https://api.kody.codes`
- URL: `https://api.kody.codes/v1/packages/{package_id}`
- Auth: HTTP bearer

Load one saved package metadata record for the signed-in user, including community-fork source listing provenance, the full export array, callable export contracts, and FYI metadata for associated package-scoped secrets (names and package_id, never values), and its credential needs with how each resolves for you (`credentials.needs`). For a single export contract, prefer search({ entity: "package:{kodyId}#{subpath}" }). Does not return README, AGENTS.md, or source files; use repoOpenSession + repoReadFile (or packageGetGitRemote) for those.

Org permission: `package:read`.

## Path parameters

- `package_id` string, required

## Response `200`

Success.

- object
  - `package_id` string, required
  - `kody_id` string, required: Package name leaf (same value as `slug`). Kept as a compatibility alias; prefer `slug` or `name`.
  - `slug` string, required: Package name leaf (the path segment after the scope). Same value as `kody_id`.
  - `name` string, required
  - `description` string, required
  - `tags` string[], required
  - `has_app` boolean, required
  - `hidden` boolean, required
  - `visibility` 'public' | 'private', required: Repo visibility / forkable. Public means default-branch HEAD is world-readable and forkable and the package appears on /community. Private is owner-only. Independent of internet_visible.
  - `internet_visible` boolean, required: When true, the hosted package app may be served on the public internet after capability approval. Independent of visibility/forkable. Defaults false.
  - `locked_at` string, nullable, required: When set, publishes require a website click at /@{username}/{kodyId}/approve-publish?commit=<full 40-character SHA>. Agents may lock via packageUpdate (`changes.locked: true`). Unlocking is website-only at /@{username}/{kodyId}/settings. Do not abbreviate the commit.
  - `source_id` string, required
  - `created_at` string, required
  - `updated_at` string, required
  - `source_listing_id` string, nullable, required: Catalog entry id this package was forked from, or null for a self-authored package.
  - `listing_current` boolean, nullable, required: Whether the source catalog entry currently resolves to an active public package, or null for a self-authored package.
  - `listing_kody_id` string, nullable, required: Original public package name leaf recorded when this package was forked, or null for a self-authored package.
  - `listing_name` string, nullable, required: Current source listing package name when the listing is active, or null when this package is self-authored or the listing is gone.
  - `origin_commit` string, nullable, required: Listing pinned commit this fork last absorbed. Starts as the fork-time snapshot and moves when a later publish passes absorbed_upstream_commit.
  - `listing_pinned_commit` string, nullable, required: Current pinned commit of the source listing, or null when this package is self-authored or the listing is gone.
  - `listing_published_at` string, nullable, required: Last community publish time of the source listing, or null when this package is self-authored or the listing is gone.
  - `listing_ahead` boolean, nullable, required: True only when this community fork is outdated: the listing pin is not an ancestor of the fork tip. Null for a self-authored package. Otherwise false.
  - `published_commit` string, nullable, required: Current published Artifacts commit for this package source (same field as `repoShowPublishNote` defaults to). Null when nothing has been published yet.
  - `exports` object[], required
    - `subpath` string, required: Package export subpath from package.json exports.
    - `import_specifier` string, required: Ready-to-use kody: import specifier for this export.
    - `runtime_target` string, nullable, required: Package-relative runtime source path for this export.
    - `types_path` string, nullable, required: Package-relative types source path for this export, when declared.
    - `description` string, nullable, required: Export description parsed from JSDoc when available.
    - `type_definition` string, nullable, required: Primary export type signature parsed from source when available. Null when the export has more than one callable function; use `functions` in that case.
    - `functions` object[], required: Callable functions extracted from this export. Namespace modules that export several helpers list each one here.
      - `name` string, required: Exported function name. Default exports use the name "default".
      - `description` string, nullable, required: Function JSDoc description when available.
      - `type_definition` string, nullable, required: Function type signature parsed from source when available.
    - `referenced_types` object[], required: Type, interface, and enum definitions referenced by this export's callable functions.
      - `name` string, required
      - `kind` 'type' | 'interface' | 'enum', required
      - `definition` string, required: Source text of the referenced type, interface, or enum.
  - `package_secrets` object[], required: FYI metadata for package-scoped secrets owned by this package, including package_id. Never plaintext values. These are not execute-usable via search; using them still requires package context.
    - `name` string, required
    - `scope` 'session' | 'package' | 'user', required
    - `description` string, required
    - `package_id` string, nullable, required
    - `allowed_hosts` string[], required
    - `allowed_packages` string[], required
    - `created_at` string, required
    - `updated_at` string, required
    - `expires_at` string, nullable, required
    - `ttl_ms` integer, nullable, required
    - `kind` 'secret' | 'url' | 'login' | 'signing': Credential kind, returned when this call set opt-in fields.
    - `provider` string, nullable
    - `inject` union
      - object
        - `kind` 'header', required
        - `name` string, required
        - `format` string, required
      - object
        - `kind` 'basic', required
        - `valueAs` 'username' | 'password', required
        - `other` string
      - object
        - `kind` 'query', required
        - `param` string, required
    - `placement` object, nullable: Where placeholders may be filled. Null means anywhere. Returned when this call set opt-in fields.
      - `headers` union
        - true
        - string[]
      - `query` true
      - `path` true
      - `body` true
  - `credentials` object, required: Credential needs (ADR 0068): the published `kody.credentials` closure, including needs inherited from statically imported packages (`from`), each with how it resolves for you. Options list only credentials you can Use; never values.
    - `needs` object[], required
      - `key` string, required
      - `kind` 'secret' | 'oauth' | 'mcp' | 'url' | 'login' | 'signing': When set, only credentials of this kind match. When omitted, any fetch-capable credential (secret, oauth, login) for the provider matches.
      - `provider` string, required
      - `description` string, required
      - `multiple` boolean, required
      - `from` string: The imported package that declares this need, when inherited.
      - `status` 'ready' | 'ambiguous' | 'unbound', required: ready: exactly one of your credentials matches the need (kind filter and provider) and resolves with no call map entry. ambiguous: several match; pick one with a call map. unbound: none match.
      - `autoPick` string, nullable, required: The credential name used when no call map entry is given.
      - `yourOptions` object[], required: Credentials you can Use that a call map may pick: the matches, plus matching-kind credentials with no provider (set their provider to auto-resolve).
        - `name` string, required
        - `scope` 'org' | 'personal', required
        - `org` string
        - `hosts` string[], required

## Other responses

- `400`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `401`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `403`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `404`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `409`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `413`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `429`: Too many requests (edge IP/token limit) or an entitlement / plan-cap limit. Wait at least `Retry-After` seconds before retrying.
- `500`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `503`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `default`: Error envelope `{ "error": { "code", "message", "details"? } }`.

---

[API](https://skmtc.dev/kody/apis/kody-api.md) · [All operations](https://skmtc.dev/kody/apis/kody-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kody/apis/kody-api/revisions/a020ecedb82b?raw)