Curations

Eg:cur-9Fw3RtYxQ7nLpK

A curation is a user-submitted correction to a native entity — a fact you’re telling OpenAlex it got wrong. OpenAlex mints its native entities by inference: it disambiguates authors from raw name strings, reads affiliations off works, decides which work each authorship belongs to. That inference is sometimes wrong, and a curation is how you push back on it: this authorship is mine, that work isn’t mine, my name should be displayed like this. Each curation records who changed what, when, and its review state — and, once applied, flows into the entity it corrects. A curation’s ID looks like cur-9Fw3RtYxQ7nLpK.

Who creates it, what states it moves through, and how it flows back

Curations come from users, not from the pipeline, so they have no “About” provenance story. Instead:

What you can curate

Curation today centers on author corrections — the entities most prone to disambiguation error. Four corrections are available, two that fix the authors attributed to a work and two that fix the names on an author profile:

  • claim work — assign a misattributed authorship on a work to your author profile.
  • remove from work — detach a work that isn’t yours from your profile.
  • modify display_name — change the displayed name on your author profile.
  • modify full_name — change the name used to match future works to your profile.

The mechanics — exact request bodies, the property anchor syntax, and how each action maps to a warehouse table — are documented in Author curation.

Site-wide curators can also correct a work’s own fields: is_retracted (true or false), type (any work type, e.g. paratext), is_xpac (false moves a work out of the expansion corpus, so default works lists, filters and searches find it; true moves it in), is_pulled (true marks a work its publisher or host withdrew or removed when no record we read says so, false clears a wrong mark; see pulled works), language (the language the work’s own text is written in, as a language code, e.g. ko), title (the work’s title as the work itself gives it, one line, for a title that arrives garbled, cut, run together with a footnote, or missing) and publication_date (an ISO date, YYYY-MM-DD, with a bare year given as its 1 January, as the work’s own pages state it). A publication_date curation is accepted only on a work with no Crossref or DataCite record: where the registrant has deposited a record, the work’s date comes from that record and an error in it is corrected there, by the registrant. These use entity works, action replace and the new value as a plain string. Two more work fields can also be cleared: abstract takes remove only (value null), for an abstract that is really the article’s full text, a fragment of it, or publisher boilerplate, and the page fields biblio.volume, biblio.issue, biblio.first_page and biblio.last_page take replace (the right value, 1 to 100 characters) or remove (value null) for a garbled one. The curated value wins over what OpenAlex computes from the work’s records from the next nightly update on.

Who can file one

Curations are recorded against the signed-in OpenAlex user account that submits them. Two kinds of user can curate:

  • Claim owners — a user who has claimed an author profile can curate that profile (and the works on it). Claim-owner edits that add works are rate-limited (1,000/day).
  • Site-wide curators and organization owners/curators — users with site-wide access can curate any author with no claim ownership, and are uncapped. Other authenticated users who are neither get a 403.

Every curation row carries the submitting user_id, so the audit trail of “who claimed what” is preserved even though it isn’t surfaced on the public read API.

The states it moves through

A curation is submitted, reviewed, and then either applied to the live data or not:

  1. Submitted. The request lands as one row with status: "pending", is_applied: false and applied_at: null. Submitting the same curation twice (same user, entity, entity_id, value, action) returns the existing row rather than creating a duplicate, so re-submitting is idempotent. A change that is already live is skipped, unless an earlier curation of the same item that says otherwise is still waiting: then the new one is recorded, and the newest wins.
  2. Reviewed and applied. Curations are picked up by the next nightly refresh of the pipeline, which starts at 05:00 UTC each day — so an accepted change is usually live within one to two days (what updates when). When a curation is seen in the live data, its status becomes applied, is_applied flips to true and applied_at records the time.

The status field says where each curation stands in one word; every OpenAlex surface (the website, the connector, this API) shows the same word.

Because curations are re-applied every cycle, an accepted correction is sticky: a removed author stays removed even if the automated matcher tries to re-attach it on a later run.

How an accepted curation flows into the entity

An applied curation rewrites the native entity it targets:

  • A work claim overwrites the author on the matching authorship, so the work now appears on the claimed author profile.
  • A work removal clears the author from that authorship, so the work drops off the profile.
  • A display_name change overwrites the profile’s displayed name and re-syncs the author’s works so the new name shows up in the API.
  • A full_name change updates the name the matcher uses, steering how future works are attributed.

Every curated work is queued to re-export to the search index on the next sync, so the correction propagates to search results, not just the entity object. For the step-by-step data flow (Postgres → per-type views → warehouse Delta tables → the live entity tables), see Author curation.

Attributes

A curation record is a compact statement of a correction: the target entity, the property to change, the change itself, and its review state. The shape below is what the curation endpoint returns; see Author curation for how each field is built.

id

String. The curation’s ID, e.g. cur-9Fw3RtYxQ7nLpK. Unlike native-entity OpenAlex IDs, it is not a resolvable openalex.org URL.

user_id

String. The ID of the user who submitted the curation, e.g. user-abc123. This is the audit trail of who made the correction; it’s stored on every row but not exposed on the public read API.

user_name

String. The display name of the submitting user, e.g. Casey M.

entity

String. Which native entity type the curation corrects — works (for claim / remove actions and work fields such as type) or authors (for display_name / full_name actions).

entity_id

String. The OpenAlex ID of the specific entity being corrected, as a full URL, e.g. https://openalex.org/W4404012345 for a work claim or https://openalex.org/A5023888391 for a name change.

property

String. The field on the target entity that the curation changes. For work claims this anchors the change to a specific byline — authorships[raw_author_name="Smith, J."].author.id — pinning the correction to one raw author name from the work. For work removals it’s the non-positional authorships.author.id. For name changes it’s simply display_name or full_name; for a work’s own field, the field’s name (is_retracted, type, is_xpac, is_pulled, language, title, publication_date, abstract, biblio.volume, biblio.issue, biblio.first_page, biblio.last_page).

action

String. What to do with the property — replace (claim a work, set a name, set a work’s own field) or remove (detach a work, or clear a work’s abstract or biblio.* field).

value

String. The new value the action applies, as a full URL where it’s an entity (the author ID for a claim or removal), a plain string for a name change (John Smith), or the field’s new value for a work’s own field (true / false for is_retracted, is_xpac and is_pulled, a work type such as paratext for type, a language code such as ko for language, the full corrected title for title, an ISO date such as 1999-01-01 for publication_date, the corrected value for a biblio.* field, null when removing a work’s abstract or biblio.* field).

created

String. The ISO 8601 datetime the curation was submitted.

status

String. Where the curation stands, one of:

  • pending: waiting to take effect, either submitted under a week ago or not checked yet.
  • timed_out: over a week old and checked at least once, but not seen in the live data yet. Not an error and not final: checks continue and it can still apply.
  • applied: seen in the live data. It records that the change took effect; a later curation of the same item can change it again.
  • superseded: a newer curation of the same item (by you or anyone else) says something different, so this one will never apply. superseded_by names it.
  • not_applied: the nightly data build won’t apply it as it stands, and the live data doesn’t show it either. Usually its target is gone: the work was merged into another or deleted, the author profile was deleted, or the name is no longer on the work’s byline. walden.reason says which. No more checks run on it, but if a later build does serve the change, it turns applied by itself.

Filter with ?status=, comma-separated for OR: ?status=pending,timed_out lists everything still open.

superseded_by

String. The ID of the newer curation that superseded this one, or null unless status is superseded.

walden

Object. What the nightly data build did with this curation the last time it ran, or null until a build has seen it (curations of works’ authors and of affiliation strings; other kinds follow). Fields:

  • outcome: applied, outranked (a newer curation of the same slot won), ignored_by_policy, target_gone, or unsupported.
  • reason: why, for example work_merged, work_deleted, profile_deleted, name_not_on_byline, or byline_name_changed (applied, but the work now prints the name another way).
  • detail: the work a merged work became (via merge into W...), or the ID of the curation that won.
  • effect_live: whether the live data shows what the curation asked for.
  • run_date: the date of the build that last changed this answer.

is_applied

Boolean. Whether the curation has been seen applied to the live entity data. Starts false on submission and flips to true once it is; status says more (an unapplied row may be pending, timed out, superseded or not applied).

applied_at

String. The ISO 8601 datetime the curation was applied, or null while it’s still pending.

In the API

Curations are submitted to POST https://user.openalex.org/curations — note the singular user. host — authenticated with your OpenAlex API key in the Authorization: Bearer header. The endpoint accepts a single JSON object or an array of them. Site curators and organization owners/curators can curate any author; a claim owner can curate their own claimed profile; other authenticated users get a 403. For the complete request shapes, the property anchor rules, and the under-the-hood data flow, see Author curation. For the full list of endpoints see the endpoints index.

Last updated

View as Markdown