---
title: "Get Atom By External Ref"
method: POST
path: "/api/v1/memory/atoms/by-external-ref"
tags: ["memory-v1"]
---

# Get Atom By External Ref

`POST /api/v1/memory/atoms/by-external-ref`

## Request

- Base URL: `https://core.mnemoverse.com`
- URL: `https://core.mnemoverse.com/api/v1/memory/atoms/by-external-ref`
- Auth: one of:
  - API key in header `X-Api-Key`
  - HTTP bearer

Resolve atom by external reference (for idempotent integration).

A ref that names a Vault secret (`secret:<alias>`) answers 404, exactly
like a ref that names no atom.

## Request body

- ExternalRefRequestSchema: Resolve atom by external reference.
  - `external_ref` string, required: External reference to resolve.

## Response `200`

Successful Response

- AtomDetailSchema: Full atom detail (for point reads and debug).
  - `id` string, uuid, required: Atom UUID.
  - `content` string, required: Stored text content.
  - `concepts` string[], required: Associated concepts.
  - `atom_type` string, required: episode, prototype, or singleton.
  - `created_at` string, required: ISO 8601 creation timestamp.
  - `last_accessed_at` string, required: ISO 8601 last access timestamp.
  - `access_count` integer, required: Number of times accessed.
  - `importance` number, required: Importance score [0, 1].
  - `valence` number, required: Outcome valence [-1, 1].
  - `outcome_count` integer, required: Number of feedback events.
  - `is_protected` boolean, required: Von Restorff singleton flag.
  - `domain` string, required: Domain namespace.
  - `external_ref` string, nullable: External reference.
  - `metadata` object: Arbitrary metadata.
  - `supersedes` string[]: Ids of the atoms this atom replaced. Empty for an unversioned atom.
  - `superseded_by` string, uuid, nullable: Id of the atom that replaced this one, or null while this is the live tip. A non-null value means this atom is marked superseded; it will be excluded from default reads once read-side filtering (D2) ships, and stays readable here by id either way.

## Other responses

- `400`: Validation error
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `422`: Validation Error
- `429`: Rate limited
- `500`: Internal server error
- `503`: Service unavailable

---

[API](https://skmtc.dev/mnemoverse/apis/mnemoverse-core.md) · [All operations](https://skmtc.dev/mnemoverse/apis/mnemoverse-core/llms.txt) · [OpenAPI document](https://skmtc.dev/mnemoverse/apis/mnemoverse-core/revisions/1f5e0048f017?raw)