API

Reading and resolving are free and unauthenticated. Writing requires a Registration Agency credential.

Read endpoints

Resolving a record

curl https://artificialpeoples.com/id/3F7K9Q2MW6TN.json

Input is normalised before validation: hyphens and whitespace are stripped, input is uppercased, and I/L map to 1 and O to 0. A valid non-canonical form redirects (301) to the canonical URL rather than rendering at two addresses.

Subjects and relations

Every record carries a subject_type: persona (the default), voice, visual_likeness, character, or work_set. Omit it on registration and you get persona.

Active records carry a relations array, in both directions — from a voice record you see what uses it, not only what it points at:

"relations": [
  {
    "direction": "incoming",
    "type": "uses_voice",
    "record_id": "TA765DBB9QFE",
    "subject_type": "persona",
    "display_name": "Night Choir",
    "basis": "license",
    "note": null,
    "asserted_by": "ra:camplifier",
    "created_at": "2026-08-02T17:00:00.000Z"
  }
]

Assert one — you must be the agency of record for the source, and both records must be active:

curl -X POST https://artificialpeoples.com/personas/{id}/relations \
  -H "Authorization: Bearer $APR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to": "9Q2MW6TN3F7K", "type": "uses_voice", "basis": "license" }'

Retract with DELETE /personas/{id}/relations/{relationId}. The retraction is soft — the row survives so the history stays legible.

Control verification

The one thing on a record that is not self-declared. A verification proves a specific narrow proposition — currently domain_control_verified: someone able to publish DNS records or web content for a named domain completed a challenge. It establishes nothing about identity, authority over any persona, or ownership of any right, and every result carries that limitation.

The flow is the ACME pattern:

« 1 » create a challenge (attach to a record with persona_id, or leave it
      free-standing for a later registration to consume)
curl -X POST https://artificialpeoples.com/verifications \
  -H "Authorization: Bearer $APR_KEY" -H "Content-Type: application/json" \
  -d '{ "proposition": "domain_control_verified", "method": "dns_txt",
        "subject": "performer.example.com", "persona_id": "3F7K9Q2MW6TN" }'

« 2 » publish what the instructions say — a TXT record at
      _apr-challenge.performer.example.com (dns_txt), or the token as the body
      of https://performer.example.com/.well-known/apr-challenge/{id}
      (https_well_known; redirects are not followed)

« 3 » run the check — retryable while DNS propagates
curl -X POST https://artificialpeoples.com/verifications/{id}/check \
  -H "Authorization: Bearer $APR_KEY"

verification_id is a decimal string, not a JSON number: the underlying value is a 64-bit integer, and one past 2⁵³ would round in any client that parses it as a number. Send it back as the string wherever it is used — the {id} above, and verification_id on POST /personas, which also still accepts the JSON number earlier releases returned.

Verified results appear in the record's verifications array and on its page, each naming its proposition, subject, method, stored verifier, dates, and limitations. Pending challenges are never public. Results expire after a year — control of a channel changes hands — and an expired verification is displayed as expired, never silently dropped.

External evidence

A record's own agency can declare that a third party's evidence bears on a narrow, named proposition about this record — never a bare badge, and never something APR has verified. Each item carries legal_effect: no_determination, the proposition it bears on, and fixed limitations text stating what it does not establish:

curl -X POST https://artificialpeoples.com/personas/{id}/evidence \
  -H "Authorization: Bearer $APR_KEY" -H "Content-Type: application/json" \
  -d '{ "evidence_kind": "registry_crosswalk",
        "proposition": "same_subject_as_external_id",
        "asserted_by": "ISNI Registry",
        "locator": "https://isni.org/isni/0000000123456789" }'

Withdraw with DELETE /personas/{id}/evidence/{evidenceId} — soft, via a new withdrawn row, so the history stays legible. Declaring evidence with supersedes_id set to an existing active item's evidence_id replaces it, rather than adding a second independent claim.

Real-person subjects require a completed control proof and an attestation

Registering a natural_voice or natural_likeness record requires consuming a completed, unattached verification and carrying an attestation, both in the same request:

curl -X POST https://artificialpeoples.com/personas \
  -H "Authorization: Bearer $APR_KEY" -H "Content-Type: application/json" \
  -d '{ "slug": "a-performers-voice", "subject_type": "natural_voice",
        "display_name": "A Performer’s Voice", "persona_type": "voice",
        "ai_disclosure": "natural", "verification_id": "42",
        "bio": "No synthetic derivation without written consent.",
        "controller": { "type": "individual", "email": "person@example.com" },
        "attestation": { "authority_basis": "subject_consent",
                          "evidence_classes": ["signed_consent"],
                          "statement_version": "0.1" } }'

The attestation is the registering agency's own declaration of what it holds, not evidence APR reviews or stores: authority_basis names why the agency may register this subject, and evidence_classes names what class of supporting material the agency holds for that basis — a signed consent document, a licence, a letter of authority, and so on (and, for these two subject types, none_held cannot be one of them — the attestation must name the class it actually holds). APR stores the declaration; it never stores the evidence, an identity document, or a consent form itself. An optional evidence_reference and attester_reference are opaque internal pointers the agency alone can resolve in its own records — an internal ticket number or a hash for evidence_reference, an internal operator code for attester_reference — never a direct identifier: a name, an email address, a phone number, a government identifier, a document URL, or the evidence itself. An internal code that identifies someone only within the agency's own records is exactly what these fields are for; it identifies no one to APR or to anyone outside the agency. own_creation ("the controller created the persona; no identifiable natural person's voice or likeness is used or imitated") cannot be used here — it contradicts a record that is, by definition, about an identifiable natural person — and is refused with 422 invalid_attestation. own_creation is also refused, on any subject, wherever ai_disclosure is or becomes digital_replica (on POST /personas, or on a PATCH that would change ai_disclosure against an existing own_creation attestation) — the two directly contradict each other; human_fronted and hybrid remain permitted alongside own_creation. evidence_classes: ["none_held"] is refused the same way, on any subject, wherever ai_disclosure is or becomes digital_replica — a digital replica is the voice or likeness of an identifiable natural person, so an attestation naming no evidence class contradicts the basis it claims.

statement_version must equal the current version — an explicit acknowledgement that the submitting agency has read what it is citing. A missing or outdated value is refused with 422 invalid_attestation, naming the current version. The text itself is uncounseled draft legal text, so — until counsel has reviewed it — it is not published here; an authenticated agency reads it at GET /attestation-statement (send your Bearer credential, same as GET /personas/lookup).

Three rules, enforced structurally: no biometric payload ever (these records may not carry an avatar_url at all); the verification must be the caller's own, completed, unexpired, and not already consumed; and the payload is consent posture, not identification. A synthetic voice built from the person's work links back with a derived_from relation, so the derivation chain is visible from the performer's own record. Domain control proves only that the registrant controls the challenged domain; it does not verify identity, consent, or authority over the person named.

Every response says what it is

Each JSON response carries a legal_effect code and the disclaimer text. Branch on status and legal_effect, not on the presence of a field — a non-active record returns a reduced representation.

An issued ID always resolves. The only case a well-formed ID returns 404 is one that was never issued.

Caching and conditional requests

Responses carry ETag and Last-Modified. Send If-None-Match and you will get a 304 when nothing has changed. Treat the ETag as opaque. It is a cache validator, not a version: it includes a deployment-scoped representation revision and covers state that is not an event — verifications lapse on the clock, so a representation can change while record_version stands still. For PATCH concurrency read the record_version field from the JSON body.

Staying current — this one is not optional

Poll the change feed rather than re-fetching records:

curl "https://artificialpeoples.com/changes?since=0&limit=100"

{
  "events": [{
    "cursor": "14",
    "event_id": "12",
    "persona_id": "3F7K9Q2MW6TN",
    "event_type": "updated",
    "actor": "ra:camplifier",
    "created_at": "2026-08-02T17:00:00.000Z"
  }],
  "next_cursor": "14"
}

event_id is the permanent event identity and the deduplication key. cursor is an opaque decimal delivery position; send the returned next_cursor back as the next exclusive since only after the page is durable. Do not convert either value through a JavaScript number. The per-record history endpoint uses the same cursor and also returns has_more.

Records get corrected, merged, withdrawn, and redacted. A stale copy of a record that was withdrawn for impersonation, or redacted at someone's request, actively causes the harm the change was meant to stop. If you cache display fields, refresh within 24 hours and propagate deprecated, withdrawn, and redacted states promptly.

A badge is a pointer, not a mirror. Always link to the canonical resolver URL.

Write endpoints — Registration Agencies

Bearer credential, issued under a signed agreement.

Taxonomies

ai_disclosure and persona_type are both closed sets, validated on POST/PATCH (422 invalid_ai_disclosure / invalid_persona_type — the schema only checks shape, so an unknown value is a semantic error like invalid_slug, not a generic 400). The response body carries accepted, the value list, alongside meanings. Every ai_disclosure value is the submitter's own declaration — APR has not verified any of them.

Registering

curl -X POST https://artificialpeoples.com/personas \
  -H "Authorization: Bearer $APR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "night-choir",
    "subject_type": "persona",
    "display_name": "Night Choir",
    "persona_type": "musician",
    "ai_disclosure": "fully_synthetic",
    "bio": "A synthetic choral ensemble.",
    "links": [{ "type": "official_site", "url": "https://example.com" }],
    "external_ref": "your-own-stable-id",
    "controller": {
      "type": "organization",
      "display_name": "Sable Labs",
      "email": "ops@example.com"
    }
  }'

controller.email and controller.legal_name are private: they are stored separately from the public record and never appear in any response.

Retrying safely

Registration issues a permanent identifier, so a blind retry is dangerous. Send external_ref on every registration. If a retry comes back 409 slug_taken or 409 external_ref_taken, call GET /personas/lookup?external_ref=… — it answers only for your own records — and confirm the existing record is your registration before adopting it.

Updating without clobbering

Send If-Match: <record_version> as a plain integer to make an update a compare-and-set. On mismatch nothing is applied and you get 409 version_conflict with current_version. Without the header the update applies unconditionally.

Lifecycle is not writable

Merges, withdrawals, and redactions are registry operations, not agency ones, and verification state is never agency-writable. Request them through the correction and challenge process.

Errors

Stability

The contract is append-only: fields and error codes may be added, none is repurposed or removed. Treat unknown fields as forward compatibility. Every route, field, header, and error code on this page is described machine-readably at GET /openapi.json (OpenAPI 3.1) — generated from, and tested against, the live route table.