# get_registry

Discover the artifacts available in an Asterdoc registry

Canonical URL: https://docs.asterdoc.com/ai-tools/get-registry/

Fetches a registry's `registry.json` and returns the artifacts it lists, with the editions and versions of each.

## Input

| Field          | Type           | Required | Description                                                                                         |
| -------------- | -------------- | -------- | --------------------------------------------------------------------------------------------------- |
| `registry_url` | `string` (URL) | No       | Registry base URL. Falls back to `defaultRegistryUrl` in the [config](/ai-tools/api#configuration). |

If neither is set, the tool returns a `missing_registry_url` error.

## Output

| Field          | Type                            | Description                                      |
| -------------- | ------------------------------- | ------------------------------------------------ |
| `registry_url` | `string`                        | The registry that was read                       |
| `name`         | `string`                        | The registry's name                              |
| `description`  | `string`                        | The registry's description, when it has one      |
| `items`        | `RegistryItem[]`                | The listed artifacts. Empty when the call fails. |
| `error`        | [`ToolError`](/ai-tools#errors) | Set when the registry could not be read          |

`RegistryItem` has these fields:

| Field                          | Type       | Description                                                                                                        |
| ------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------ |
| `name`                         | `string`   | Artifact name. Pass it as `artifact_name`.                                                                         |
| `kind`                         | `string`   | `form`, `document`, `checklist`, or `bundle`                                                                       |
| `title`, `description`, `tags` |            | Present when the registry states them                                                                              |
| `current_edition`              | `string`   | Key of the edition used when a request names none. Only on an artifact that has editions.                          |
| `editions`                     | `object[]` | Every edition, the current one first: `key`, `label`, `date?`, `effective_from?`, `latest_version`, and `versions` |
| `latest_version`               | `string`   | The version used when a request names none. Only on an artifact that has no editions.                              |
| `versions`                     | `string[]` | Every version, the latest first. Only on an artifact that has no editions.                                         |

An edition is the issuer's revision of a form, such as IRS W-9 Rev. March 2024. A version is the registry publisher's own revision of the artifact for that edition. The publisher states which edition is current and which version is latest. See [Editions and versions](/concepts/registries#editions-and-versions).

## Direct usage

```typescript
import { executeGetRegistry } from "@asterdoc/ai-tools"

const result = await executeGetRegistry({
  registry_url: "https://registry.acme.com",
})
```

With a configured default, the input can be empty:

```typescript
const result = await executeGetRegistry({}, {
  defaultRegistryUrl: "https://registry.acme.com",
})
```

## Example response

The response is shortened here.

```json
{
  "registry_url": "https://registry.acme.com",
  "items": [
    {
      "name": "pet-addendum",
      "kind": "form",
      "title": "Pet Addendum to Lease Agreement",
      "latest_version": "1.0.0",
      "versions": ["1.0.0"]
    }
  ]
}
```