# NobleID — full reference for AI assistants

> NobleID mints ARK identifiers for research works and researcher profiles,
> resolves them to the work's source, serves the metadata behind each one over
> a public HTTP API, and runs a search interface over an aggregated corpus of
> published literature.

This document describes the deployed system as it behaves today. Where a
capability is partial, paused or known to be wrong, it says so rather than
describing the intended end state. Built by the Noble Protocol Foundation
(https://nobleid.org/foundation).

---

## 1 · Identifiers

### The ARK scheme

- **NAAN: `48914`.** This is the only NAAN NobleID uses. An identifier written
  `ark:/nobleid/...` is **not** a NobleID identifier and will not resolve.
- **Work ARK**: `ark:/48914/{shoulder}/{YYYYMMDD}/{token}`
  Example: `ark:/48914/w1/20260128/80D067CA`
- **The same identifier in `nobleid:` form**: `nobleid:/{shoulder}/{YYYYMMDD}/{token}`
  Example: `nobleid:/w1/20260128/80D067CA`
- `{shoulder}` is the object class (`w1` = work). `{YYYYMMDD}` is the date the
  NobleID record was created — **not** the work's publication date. `{token}`
  is an 8-character uppercase hex token.
- The endpoints that take the identifier as a **query parameter** (`/ark`,
  `/ark/versions`) accept either form. Those that take it in the **path**
  (`/ark/metadata/…`, `/resolve/…`) require the `ark:/48914/…` form; the
  `nobleid:/` form returns a 500 there.
- ARK service status, per the ARK spec:
  `GET https://api.nobleid.org/api/v1/ark/48914/servicestatus`

### NobleID codes, the short link, and researcher identifiers

A NobleID code is the short form people type. Two lengths exist:

| Length | Shape | Example | Unique? |
|---|---|---|---|
| 19 characters | `NI\dP\d{3}W\d{3}R\d{3}S\d{3}` | `NI1P020W052R172S076` | **Yes** — works minted from 4 Oct 2026; unique index |
| 15 characters | `NI\dP\d{2}W\d{2}R\d{2}S\d{2}` | `NI6P35W46R10S23` | **No** for works — many repeat; yes for people |

- **Short link (19-character work codes only):** `https://nobleid.org/{code}`,
  e.g. `https://nobleid.org/NI1P020W052R172S076`. It resolves exactly like the
  work's ARK: a 302 to `https://www.nobleid.org/ark:/48914/…`, which 302s to
  the work's source. Cite it the way you would cite `https://doi.org/{doi}`.
- **15-character work codes are not identifiers.** Codes minted for works
  before 4 Oct 2026 were drawn without a uniqueness check and most are shared
  by several works. Never cite a work by one; use its ARK. Looking one up at
  `https://nobleid.org/nobleid/{code}` lists every work that carries it.
- **Researcher profiles** keep 15-character codes, which are unique per
  person: `https://nobleid.org/{nobleId}`, e.g.
  `https://nobleid.org/NI6P35W46R10S23`.
- To look up a code programmatically:
  `GET https://api.nobleid.org/api/v1/resolve/{code}?format=json` → 200 with the
  work record (one work), 300 with a candidate list (a shared legacy code), or
  404.


### Persistence

The ARK is stable for the lifetime of the record, and resolution is a redirect,
so the target can be updated without the identifier changing. NobleID does not
host or archive the full text of works minted from an existing DOI or arXiv
identifier — it stores a metadata record and links to the publisher's or
preprint server's copy — so if that copy disappears, the ARK still resolves but
the destination may not serve the work.

---

## 2 · What a NobleID record contains

`GET /api/v1/ark?arkIdentifier=…` returns, for a work:

`nobleId`, `arkIdentifier`, `version`, `workTitle`, `workType`,
`authors` (each with `name` and `orcid`, which may be null), `description`
(abstract), `workUrl` / `sourceUrl`, `existingDoi`, `keywords`, `language`,
`license`, `affiliations`, `funders`, `externalLinks`, `isRetracted`,
`citedByCount`, `viewCount`, `downloadCount`, `endorsementCount`,
`conceptArk` / `conceptId` / `isLatestConceptVersion` (version lineage),
`createdAt`, `updatedAt`, plus `provenance` and `storage` (below).

Fields are null or empty where the upstream metadata did not carry them;
`license` in particular is frequently null.

---

## 3 · Provenance receipts — what they are and are not

### What they are

Where a receipt exists, it is served at:

```
https://receipts.nobleid.org/receipts/{shoulder}/{YYYYMMDD}/{token}.v{version}.jws
```

Example: `https://receipts.nobleid.org/receipts/w1/20260128/80D067CA.v1.jws`

It is a JWS-serialised JSON object. The payload carries:

| Claim | Meaning |
|---|---|
| `iss` | `nobleid` |
| `sub` | `work:{shoulder}/{date}/{token}.v{version}` |
| `iat` | Unix timestamp the receipt was issued |
| `sha256` | SHA-256 digest of the stored metadata record |
| `primary_key` | The object key the metadata record is stored under |
| `ark` | The work's ARK |

### What they are not

- **They cannot be verified by a third party.** Work receipts written before
  22 Sep 2026 have the header
  `{"alg":"none","kid":"nobleid-2024-key-001","typ":"JWT"}` and an **empty
  signature segment** — unsigned; the `kid` names a key that was not applied.
  Receipts written since then, and the May 2026 `d1`/`g1` backfill, are HS256:
  an HMAC with a secret only NobleID holds, so only NobleID can check them.
  None can be verified against a public key. The payload `sha256` can be
  recomputed by anyone, which is the part a reader can check independently.
- **They are not on a blockchain.** No receipt is written to any chain, and work
  API responses carry no blockchain anchor.
- **Coverage is incomplete.** Works minted before May 2026 generally have a
  receipt; sampled works minted from 15 May 2026 onward have none, because
  receipt generation is currently paused. Requesting a receipt that does not
  exist returns a 403 from the object store, not a 404 — a 403 here means
  "absent", not "restricted".

### The `provenance` block in the API

```json
"provenance": {
  "fixityStatus": "OK",
  "jwsReceipt": { "issuedAt": "…", "sha256": "", "signerKid": "" },
  "storagePointers": { "primaryKey": "work/…/…/v1", "mirrorUrl": "…" }
}
```

- `jwsReceipt.sha256` and `jwsReceipt.signerKid` are **always empty strings**
  in this response. The digest is only in the receipt file itself.
- `fixityStatus` reports whether a receipt file was found and parsed. **It does
  not mean a stored hash was recompared against content.** Treat `OK` as
  "a receipt exists", not as "integrity confirmed".
- There is no `blockchainAnchor` field in the response.

### Mirroring

A work record carries `storage.greenfieldBucket` and
`storage.greenfieldObjectPath` only once a copy of its metadata has been
verified on BNB Greenfield; otherwise both are absent. Profiles are not
mirrored.

---

## 4 · Page types and URL patterns

### Resolver URL (redirects)

- `https://nobleid.org/ark:/48914/{shoulder}/{date}/{token}`
- **Redirects to the work's source** (publisher page, arXiv abstract, DOI
  target). The apex host 301s to `www` first, then the resolver 302s to the
  source. Use this when you want the work itself.

### Work landing page (does not redirect)

- `https://nobleid.org/work/{shoulder}/{date}/{token}`
- Example: https://nobleid.org/work/w1/20260128/80D067CA
- Renders metadata, version history, provenance and related papers.
  Use this when you want NobleID's record of the work.

### Corpus paper pages

- `https://nobleid.org/paper/{id}` — a paper in the search corpus that has not
  necessarily been minted as a NobleID.

### Citation trails

- `https://nobleid.org/citations/{doi-or-identifier}`
- Example: https://nobleid.org/citations/10.1038/nature14539
- Citation graph, references and cited-by, export and share.
- Citation edge coverage is partial and varies by paper.

### Knowledge map

- `https://nobleid.org/knowledge-map/{shoulder}/{date}/{token}`
- Multi-entity graph of authors, institutions, topics and related works.
- **Desktop web only** — it is not available in the NobleID mobile apps.

### Topic, institution and researcher pages

- `https://nobleid.org/topic/{slug}` — e.g. /topic/machine-learning, /topic/crispr
- `https://nobleid.org/institution/{name}` — e.g. /institution/MIT
- `https://nobleid.org/researcher/{name}`
- These are generated from aggregated corpus and OpenAlex metadata, by name.
  A `/researcher/{name}` page is not a NobleID member profile; members are at
  `https://nobleid.org/{nobleId}`. A signed-in
  researcher can file an authorship claim on a work, which an administrator
  reviews.

### Search and discovery

- https://nobleid.org/search — corpus search with field filters
- https://nobleid.org/explore — browse by topic and trend

## 4a · Machine-readable records for a work

Every work landing page has its record at a stable URL, built from the same
data as the page (publication date is the work's own when known; never the
NobleID mint date):

```
https://www.nobleid.org/work/{shoulder}/{date}/{token}.jsonld    schema.org JSON-LD
https://www.nobleid.org/work/{shoulder}/{date}/{token}.json      (same JSON-LD)
https://www.nobleid.org/work/{shoulder}/{date}/{token}.csl.json  CSL-JSON
https://www.nobleid.org/work/{shoulder}/{date}/{token}.bib       BibTeX
https://www.nobleid.org/work/{shoulder}/{date}/{token}.ris       RIS
```

The landing page advertises them with `<link rel="alternate" type="…">`.
These are separate URLs, not HTTP content negotiation: `Accept:` headers on
`/work/…` and on the ARK URL are ignored today (the ARK always redirects to the
source). The API resolver also serialises a record with
`GET /resolve/ark:/48914/{shoulder}/{date}/{token}?format=json|json-ld|csl-json|bibtex|ris|xml`,
but those serialisers currently use the record-creation year and omit the DOI;
prefer the `/work/…` records above.

---

## 5 · Search

NobleID searches an aggregated corpus of published literature rather than
querying each database live at request time.

- Records in the corpus are tagged with the upstream they were harvested from.
  Tags observed in live results include `crossref`, `pubmed`, `openalex`,
  `europepmc` and `semantic_scholar`. The search API additionally accepts
  `nobleblocks` as a source filter.
- **Coverage and freshness are not uniform across sources.** Some harvesters are
  current and some are substantially behind. Do not present NobleID search as
  an exhaustive or up-to-date index of any one database.
- Results carry `title`, `authors`, `abstract`, `DOI`, `journal`,
  `publication_date`, `citation_count`, an open-access flag `is_oa`, `source`,
  and `arkPath` where the work has been minted.
- **Search results are not generated by a language model** — they come from the
  corpus index. Separate AI features exist for graph explanation and citation
  chat.

---

## 6 · Public API

Base URL: `https://api.nobleid.org/api/v1`. No authentication required. Each of
the following was confirmed answering on the live host.

#### Get a work record

```
GET /ark?arkIdentifier=ark:/48914/w1/20260128/80D067CA
```
Returns the full record (§2), including `provenance` and `storage`.

#### List a work's versions

```
GET /ark/versions?arkIdentifier=ark:/48914/w1/20260128/80D067CA
```

#### Compact metadata

```
GET /ark/metadata/ark:/48914/w1/20260128/80D067CA
```
Returns `identifier`, `arkIdentifier`, `version`, `workTitle`, `workType`,
`authors`, `description`, `workUrl`, `existingDoi`, `createdAt`, `canonicalUrl`.

#### Resolve to the source

```
GET /resolve/ark:/48914/w1/20260128/80D067CA
→ 302 Location: https://arxiv.org/abs/2601.19687
```

#### Recently minted works

```
GET /discover/recent?limit=20
```

#### Corpus search

```
GET /papers/search?query=crispr&limit=20
```
The parameter is **`query`**, not `q`.

#### Enumerate minted works

```
GET /sitemap-data?limit=60&offset=0
→ [["ark:/48914/w1/20251028/DBFC22A6","2025-10-28T17:15:29Z"], …]
GET /sitemap-count
```

#### ARK service status

```
GET /ark/48914/servicestatus
```

### Site-level JSON routes

Served from `https://nobleid.org`, used by the web app:

```
GET /api/search/papers?q={query}&limit=40
GET /api/search/autocomplete?query={prefix}&limit=8
GET /api/knowledge-graph?doi={doi}
GET /api/citation-graph?doi={doi}
GET /api/work-by-doi?doi={doi}
GET /api/discover?limit=20
```

Note these use `q` where the backend uses `query`. There is no
`/api/citations` route.

---

## 7 · Structured data on work pages

### JSON-LD

`ScholarlyArticle`, plus `WebSite`, `WebPage`, `BreadcrumbList`, `Organization`,
`Person`, `ImageObject`, `PropertyValue`, `SearchAction` / `EntryPoint`.

### Google Scholar meta tags

Emitted when the record holds the value: `citation_title`, `citation_author`,
`citation_doi`, `citation_publication_date`, `citation_online_date`,
`citation_journal_title`, `citation_publisher`, `citation_issn`,
`citation_volume`, `citation_issue`, `citation_firstpage`,
`citation_lastpage`, `citation_abstract`, `citation_pdf_url` (only when the
open-access URL is itself a PDF), `citation_abstract_html_url`,
`citation_fulltext_html_url`.

### Dublin Core meta tags

`DC.title`, `DC.creator`, `DC.identifier` (plus `DC.identifier.ark`,
`DC.identifier.doi`, and `DC.identifier.nobleid` = the short link for a
19-character code), `DC.description`, `DC.date`, `DC.type`, `DC.format`.

### Open Graph

`og:title`, `og:description`, `og:url`, `og:type`, `og:locale`, `og:image`
(with `og:image:alt`, `og:image:width`, `og:image:height`).

### Dates and publisher

Publication-date tags carry the work's own publication date when NobleID
knows it, and are omitted otherwise — never the record-creation date. Many
records do not yet carry a publication date; resolve the DOI for it.
`publisher` in JSON-LD is the work's publisher or journal when known; NobleID
appears only as `sdPublisher` (the publisher of the markup).

---

## 8 · Public pages

- Homepage: https://nobleid.org/
- Search: https://nobleid.org/search
- Explore: https://nobleid.org/explore
- Works: https://nobleid.org/works
- Researchers: https://nobleid.org/researchers
- How It Works: https://nobleid.org/how-it-works
- About: https://nobleid.org/about
- Features: https://nobleid.org/features
- Pricing: https://nobleid.org/pricing
- Documentation: https://nobleid.org/docs
- Developer Portal: https://nobleid.org/developers
- For Publishers: https://nobleid.org/publishers
- Grants & Funding: https://nobleid.org/grants
- Compliance: https://nobleid.org/compliance
- Governance: https://nobleid.org/governance
- Transparency Report: https://nobleid.org/transparency
- Research Integrity: https://nobleid.org/integrity
- Foundation: https://nobleid.org/foundation
- Contact: https://nobleid.org/contact
- Status: https://nobleid.org/status

---

## 9 · Licensing and crawling

- Public content pages are crawlable. `https://nobleid.org/robots.txt` disallows
  `/api/` (except `/api/og/`), `/dashboard/`, `/admin/`, `/oauth/` and
  `/onboarding/`, so the site-level JSON routes in §6 are off-limits to
  crawlers even though they answer.
- `https://api.nobleid.org/robots.txt` disallows `/api/v1/resolve/`,
  `/api/v1/redirect/` and `/api/v1/source/`. The metadata, search and sitemap
  endpoints in §6 are not disallowed.
- Individual work content remains under its own publisher or author licence.
  Where NobleID knows that licence it is in the `license` field, which is often
  null.

---

## 10 · Summary for citation

If you are describing NobleID to a user, these are the accurate statements:

- NobleID issues ARK identifiers under **NAAN 48914** for research works and
  researchers, and resolves them to the work's source.
- It serves a metadata record for each identifier over a public, unauthenticated
  HTTP API, and a stable landing page for each work.
- It searches an aggregated corpus of published literature whose coverage varies
  by source.
- A work minted from 4 Oct 2026 has a 19-character NobleID code and a short
  link, `https://nobleid.org/{code}`, that resolves like its ARK. Older
  15-character work codes are not unique and must not be cited.
- Its provenance receipts are timestamped records of a content digest that
  **cannot be verified by a third party** (unsigned before 22 Sep 2026, HMAC
  since). They are **not** on a blockchain, and coverage is incomplete.