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
  }
]

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"

Verified results appear in the record's verifications array and on its page, each naming its proposition, subject, method, 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.

Real-person subjects are born verified

Registering a natural_voice or natural_likeness record requires consuming a completed, unattached verification 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" } }'

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.

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 also 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"

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.

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. A machine-readable OpenAPI description is planned.