API reference

Reference for Prosopia’s HTTP API. Prosopia runs on port 8200 at prosopia.databio.org (profiles.databio.org points to the same app).

Authentication

Prosopia accepts three kinds of credentials.

A signed, HTTP-only cookie named rp_session, set after ORCID or Google login. The React app uses this automatically. Most /api/manage/* routes require it.

API key

Authorization: Bearer <key>

Two key types, distinguished by prefix:

rpk_ (app key): operator-minted, carries app scopes (read, match, persona, push).
rpa_ (agent key): owner-minted for one profile, carries agent scopes (profile:metadata, profile:history, profile:identity, profile:narrative, profile:visibility). Cannot use app scopes (403).

The plaintext is returned only once at mint time; the server stores its hash. Each key also carries a viewer tier.

Errors: 401 missing or invalid key; 403 insufficient scope.

Operator token

Authorization: Bearer <token>

Set by RESEARCHER_PROFILES_TOKEN. Superuser — holds every scope and reads at restricted tier. Administrative, not a shared app credential.

Viewer tiers

Every read is projected through the caller’s viewer tier: public, internal, or restricted (least to most permissive).

Caller	Tier
No credential	`public`
Person with no permission from the profile’s owner	`public`
API key	the tier minted on the key (default `public`)
The owner, a co-owner, or an editor of the profile	`restricted`
Anyone holding a `read` or `write` permission on the owner	`restricted`
Operator token	`restricted`

Reading is all-or-nothing: a permission is a whole read.

Response headers: X-RP-Viewer-Tier on every read; X-RP-Effective-Tier on single-artifact reads.

An artifact above the caller’s tier returns 404. An unpublished profile is floored at internal, so anonymous callers see only published profiles.

GET /api/manage/session

Session probe. Always 200, never 401. Returns authenticated, login_configured, login_url, user ({orcid, name} or null), owned (profiles you own), claimable, creatable, build_available, is_operator.

GET /api/manage/login

Redirects to the OAuth provider. 503 if no login provider is configured.

GET /api/manage/callback

OAuth callback. Verifies state, exchanges code, sets the session cookie, redirects to /. Errors: 400 invalid state; 502 token exchange failure.

POST /api/manage/logout

Deletes the session cookie. Returns {"authenticated": false}.

Reading profiles

These routes have no credential gate. What the caller sees depends on their viewer tier.

GET /api/v1/profiles: profile listing.
GET /api/v1/profiles/{slug}: profile detail.
GET /api/v1/profiles/{slug}/content/{artifact}: one artifact, projected through the caller’s tier.
GET /api/v1/profiles/{slug}/papers: paper inventory.
GET /api/v1/profiles/{slug}/summary/{paper_id}: one paper summary.
GET /api/v1/registry.json: registry bundle. Cached for anonymous callers; private, no-store for credentialed callers.

{slug} also accepts a rid.

Creating a profile

POST /api/manage/profiles — session required.

Request: {"name"?: str, "slug"?: str}. Both optional; name falls back to login name. Creates a minimal private profile (lite, internal) with the ownership row in one transaction.

Response 201: {slug, rid, level, visibility, edit_urls}. Errors: 400 bad name or slug; 401 not logged in; 409 profile already exists or slug taken.

Deleting a profile

DELETE /api/manage/profiles/{slug} — owner only. Response 204.

Editing a profile

Owner or editor (session or agent key with the right scope):

PATCH /api/v1/profiles/{slug}/metadata: edit metadata fields.
PUT /api/v1/profiles/{slug}/soul: set the narrative.
PATCH /api/v1/profiles/{slug}/visibility: set visibility tiers.

An agent key can only narrow visibility, never widen it. Insufficient scope returns 403 with {error, required, granted, missing, hint}.

Claiming a profile

POST /api/manage/claims — session required.

Claim a profile whose ORCID matches yours. Request: {"slug": "<slug>"}. Response 201: {slug, rid, owned}. Errors: 403 ORCID mismatch; 404 no such profile; 409 already claimed.

Identity resolution

GET /api/v1/identity/resolve — gated. Query: rid= or orcid=. Returns {slug, rid, claimed, owner_orcid}. Anonymous callers see only profiles that are published AND publicly visible; a signed-in session, the operator token, or any live rpk_ consumer key sees the rest (restricted profiles answer only to a signed-in session). 404 means “not visible to you” — it does NOT prove the identity is absent, so never treat a 404 here as a green light to create; use POST /api/v1/identity/resolve (the resolver) for that decision.

POST /api/v1/identity/resolve — requires the resolve scope (a write scope: a true miss mints a stub profile). Body: {rid?, name?, affiliation?, create_new?}. Returns {rid, created, confidence}; an undecidable name returns rid: null with candidates — re-resolve with the chosen candidate’s rid, or with create_new: true to mint a fresh identity when no candidate is the caller’s person.

Publication

Publication is the owner’s decision to put a profile on the open web. Until published, a profile is floored at internal — anonymous callers get 404.

GET /api/manage/profiles/{ref}/publication

Publication state. Owner or editor may read; only the owner sees actor identities and history.

Returns: {slug, rid, published, published_at, revoked_at, profile_visibility, floor, visible_to_anonymous, still_visible_to}.

POST /api/manage/profiles/{ref}/publication

Publish or unpublish. Owner only — editors, apps, and the operator token are all refused.

Request: {"published": bool, "confirm"?: str, "profile_visibility"?: str}. Publishing requires confirm equal to the slug. Unpublishing does not. profile_visibility optionally sets the document tier in the same request.

Unpublishing sets an internal floor but is not a blackout: permission holders, managers, internal/restricted keys, and operators keep reading.

Permissions

A permission is (owner_id, principal, grant_type): may principal read or write everything owner holds — every profile they own and every lens they authored. Keyed on the person whose data it is, never on one profile. write implies read.

GET /api/manage/permissions — the signed-in person’s list: every permission others hold on their data.
POST /api/manage/permissions — signed-in person. Request: {principal_kind, principal_ref, grant_type}. principal_kind is user (ORCID) or consumer (id/name); grant_type is read or write. Response 201.
DELETE /api/manage/permissions/{permission_id} — signed-in person; 404 unless the permission is on their data.

Managers

Co-management is per profile and people-only: (profile_rid, user_id, role) with roles co-owner (everything the owner may do except transfer) and editor (rewrite the document; may not publish, delete, or manage access).

GET /api/manage/profiles/{slug}/managers — owner or any manager.
POST /api/manage/profiles/{slug}/managers — owner only. Request: {orcid, role}. Response 201.
DELETE /api/manage/profiles/{slug}/managers/{manager_id} — owner only. Ownership itself is not revocable here. 404 no such manager.

Suggestions

Every consumer overlay on a profile appears to the owner as a suggestion.

GET /api/manage/profiles/{slug}/suggestions — owner only.
POST …/suggestions/{id}/accept — apply the overlay to the canonical profile. Owner only.
POST …/suggestions/{id}/dismiss — mark dismissed; the consumer keeps its private overlay. Owner only.

On-demand builds

Prosopia records a build request and hands it to a remote runner. All build endpoints return 503 when no runner is configured.

Two build paths:

Self-service: the owner runs the researcher-profile Claude Code skill on their own AI. This does not use any endpoint below. See How to build a profile.
Admin-triggered: an operator builds any profile from the admin panel.

POST /api/manage/profiles/admin/build/{ref}

Enqueue a build. Operator only. Request: {"level": "full"} (or "lite"; "deep" is refused). One build at a time per profile.

Response 202: {job_id, status, level, requested_at, started_at, completed_at, error, phases_completed, runner}. Errors: 409 build already active; 503 no runner.

GET /api/manage/profiles/admin/build/{ref}

Latest build status. Operator only.

POST /api/manage/profiles/{ref}/build (deprecated)

Owner-facing enqueue. Deprecated in favor of the self-service skill.

GET /api/manage/profiles/{ref}/build (deprecated)

Owner-facing status. Deprecated.

POST /api/manage/profiles/{ref}/build/callback

Runner progress callback. Authenticated by PROSOPIA_BUILD_CALLBACK_TOKEN, not a session. Request: {job_id, status, phases_completed?, error?}.

Search and AI

These require an API key with the appropriate scope.

POST /api/v1/match: cross-profile ranking. Scope: match.
POST /api/v1/profiles/{slug}/search: semantic search. Scope: match.
POST /api/v1/profiles/{slug}/{ask,review,innovate,riff}: persona endpoints. Scope: persona.

Overlays

An overlay is a consumer-private patch over a canonical profile, keyed by (profile_rid, consumer_id). Only the authoring consumer sees the merged view; everyone else sees canonical alone. Requires an API key (person sessions get 403).

GET /api/v1/profiles/{slug}/overlay: the consumer’s overlay and merged view. 404 if none exists, unless ?create=merged.
PUT …/overlay/metadata: write the metadata patch. Request: {"patch": {...}}.
PUT …/overlay/soul: set or clear the soul override. Request: {"soul": <str|null>}.
PATCH …/overlay/visibility: set the visibility patch. Request: {"profile_visibility"?: str, "artifacts"?: [...]}.
DELETE …/overlay: discard the overlay.

Write routes return {overlay, merged, stale}. The overlay records the canonical base_hash it was authored against; a later canonical edit marks overlays as stale.

Person links

A consumer binds its own external ids (e.g. a faculty member id) to canonical profiles.

GET /api/manage/consumers/{consumer}/person-links/{external_id}: resolve the consumer’s id to {consumer_id, external_id, slug, rid}. Must authenticate as the named consumer.
POST /api/manage/consumers/{consumer}/person-links: bind one. Request: {external_id, slug?, rid?}. Response 201.
GET /api/manage/profiles/{slug}/person-links: owner/editor view of which consumers reference this profile.

Agents

An agent is a consumer owned by a person, scoped to write specific fields on that person’s profile via an rpa_ key.

Managing agents (session required)

GET /api/manage/agents: list your agents.
POST /api/manage/agents: mint one. Request: {label, profile, scopes, expires_at?}. Returns the plaintext key once. Response 201.
POST /api/manage/agents/{id}/rotate: revoke and re-mint the key.
PATCH /api/manage/agents/{id}: update label or scopes.
DELETE /api/manage/agents/{id}: revoke the agent and its keys.
GET /api/manage/agents/{id}/activity: the agent’s edits and audit.

Agent self-service (agent key required)

GET /api/manage/agent/whoami: the agent’s authority — principal, owner, profiles, tier, scopes. 400 for app keys.
GET /api/manage/agent/scopes: scope catalog. Unauthenticated.

Agent scopes:

Scope	Fields
`profile:metadata`	`field`, `subfields`, `summary`, `expertise`, `interests`, `not_interests`
`profile:history`	`training`, `career`
`profile:identity`	`name`, `affiliation`, `job_title`, `same_as`
`profile:narrative`	the soul narrative
`profile:visibility`	profile and artifact tiers (narrow only)

Push and archive

Scope: push (API key or operator token).

PUT /api/v1/profiles/{slug}: push a full profile.
GET /api/v1/profiles/{slug}/archive: download archive.

Consumer admin

Operator-only CRUD for consumer apps and their keys. Requires the operator token or a session on PROSOPIA_ADMIN_ORCIDS.

Method	Path	Purpose
GET	`/api/admin/consumers`	List all consumers with key counts
POST	`/api/admin/consumers`	Register a consumer (`409` duplicate)
GET	`/api/admin/consumers/{id}`	Full detail with all keys and audit
PATCH	`/api/admin/consumers/{id}`	Update description or active status
DELETE	`/api/admin/consumers/{id}`	Deactivate and revoke all keys
POST	`.../keys`	Mint an `rpk_` key
POST	`.../keys/{key_id}/rotate`	Revoke and re-mint
POST	`.../keys/{key_id}/revoke`	Revoke a key
GET	`.../audit`	Recent attributed calls

Valid key scopes: read, match, persona, push. Valid key tiers: public, internal, restricted.

Other endpoints

GET /health: liveness probe. Unauthenticated.
GET /context/v1.jsonld: JSON-LD @context document. Cached, anonymous.

Errors

All errors return {"detail": "<string>"} except agent-scope denials, which return a structured detail with error, required, granted, missing, and hint.

Internal developer notes, in the Prosopia source tree rather than on this site: dev-docs/database.md (stored tables), dev-docs/architecture.md (the one-database model), and dev-docs/configuration.md (environment variables).