# get_artifact

Retrieve one artifact and its instructions from a Paradoc registry

Canonical URL: https://docs.paradoc.dev/ai-tools/get-artifact/

Retrieves one artifact from a registry. The tool reads `registry.json`, checks the artifact is listed, and fetches it. By default it also returns the artifact's `instructions` and `agentInstructions`.

## Input

| Field                        | Type           | Required | Description                                                                                         |
| ---------------------------- | -------------- | -------- | --------------------------------------------------------------------------------------------------- |
| `registry_url`               | `string` (URL) | No       | Registry base URL. Falls back to `defaultRegistryUrl` in the [config](/ai-tools/api#configuration). |
| `artifact_name`              | `string`       | Yes      | Artifact name within the registry                                                                   |
| `include_instructions`       | `boolean`      | No       | Return the artifact's `instructions`. Default `true`.                                               |
| `include_agent_instructions` | `boolean`      | No       | Return the artifact's `agentInstructions`. Default `true`.                                          |

## Output

| Field                | Type                            | Description                                                                                                               |
| -------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `artifact`           | `object`                        | The artifact JSON (form, document, bundle, or checklist)                                                                  |
| `artifact_name`      | `string`                        | The requested name                                                                                                        |
| `base_url`           | `string`                        | The artifact's directory. Pass it as `base_url` in an [artifact source](/ai-tools#sources) so file-backed layers resolve. |
| `instructions`       | `InstructionContent`            | The artifact's instructions, when present and requested                                                                   |
| `agent_instructions` | `InstructionContent`            | The artifact's agent instructions, when present and requested                                                             |
| `error`              | [`ToolError`](/ai-tools#errors) | Set when the artifact could not be fetched, for example `artifact_not_found`                                              |

`InstructionContent` has these fields:

| Field       | Type                  | Description                                    |
| ----------- | --------------------- | ---------------------------------------------- |
| `kind`      | `"inline" \| "file"`  | Inline text or a file next to the artifact     |
| `mime_type` | `string`              | File MIME type (file only)                     |
| `path`      | `string`              | File path relative to the artifact (file only) |
| `content`   | `string`              | The instruction content                        |
| `encoding`  | `"utf-8" \| "base64"` | `utf-8` for text, `base64` for binary files    |

## Direct usage

```typescript
import { executeGetArtifact } from "@paradoc/ai-tools"

const result = await executeGetArtifact({
  registry_url: "https://public.paradoc.dev",
  artifact_name: "pet-addendum",
})
```

## Example response

The artifact is shortened here. The real registry response also includes file-backed `instructions` and `agent_instructions` entries.

```json
{
  "artifact": {
    "kind": "form",
    "name": "pet-addendum",
    "version": "1.0.0",
    "title": "Pet Addendum to Lease Agreement",
    "fields": { "petName": { "type": "text", "label": "Pet name", "required": true } }
  },
  "artifact_name": "pet-addendum",
  "base_url": "https://public.paradoc.dev/pet-addendum"
}
```