# Living Portraits > Paintings whose characters live on LED panels. Each character is an AI agent with a pose, a goal, a mood and a journal. This API lets a partner (or their agent) watch the characters, read their memory, and design new ones within limits. MCP (streamable HTTP, bearer token): https://portraits.skew.site/mcp OpenAPI: https://portraits.skew.site/v1/openapi.json REST base: https://portraits.skew.site/v1 Auth: Authorization: Bearer lp__. Kinds: admin, partner (your paintings only), box (one painting box), studio (generation worker). Tokens come from the platform admin. Every response: {"ok":true,"data":...} or {"ok":false,"error_kind":...,"message":...,"fix":...}. When ok is false, do what fix says. ## Start Living Portraits: paintings whose characters live on LED panels, each an AI agent with a pose, goal, mood and journal. Start with whoami (what your token can do), then paintings_list. agent_status shows what each character is doing now; memory_search and memory_stats read its journal. To make a new character: archetypes_list (the limits), then character_create (use dry_run=true first; it spends one of the monthly creations), poll character_list until it is ready, then character_assign. Every result is {ok:true,data} or {ok:false,error_kind,message,fix}; when ok is false, do what fix says. ## Operations - whoami (GET /v1/whoami; admin/partner/box/studio): Read-only. Returns the kind of token you hold (admin / partner / box / studio), the partner account and plan it belongs to, and how many character creations are left this month - paintings_list (GET /v1/paintings; partner/admin): Read-only. Lists the paintings your token can see, each with online state (a heartbeat within the last 90 s), last heartbeat time, runtime version, release channel, panels, and which character is live on each panel - agent_status (GET /v1/paintings/:id/agents; partner/admin): Read-only. For one painting, what each character is doing right now: pose label, current goal, mood, seconds in the current pose (dwell), the last thing it said, and since when - memory_search (GET /v1/characters/:id/memory; partner/admin): Read-only. Searches one character's journal: lines it said, things it wanted, and reflections, newest first - memory_stats (GET /v1/characters/:id/stats; partner/admin): Read-only. Aggregate stats for one character: total journal entries, entries by kind, entries per day for the last 30 days, how many distinct poses it has visited, its top poses by time spent, and how many days it has been alive on the wall. - archetypes_list (GET /v1/archetypes; partner/admin/studio): Read-only. The rules character_create enforces: the 8 archetypes (each with its allowed settings, big-five slider bands and motion vocabulary), the setting palettes, the global chaos / fourth_wall sliders, name and quirk length limits, the content-filter categories, and the monthly budget defaults - character_create (POST /v1/characters; partner/admin): CHANGES STATE and SPENDS BUDGET. Designs a new character for a panel of one of your paintings and queues it for generation (status `queued`; the studio then moves it to generating and ready) - character_list (GET /v1/characters; partner/admin): Read-only. Lists your characters with their status: queued (waiting for the studio), generating, ready (can be assigned), live (on the wall), retired, rejected (with the reason) - character_assign (POST /v1/characters/:id/assign; partner/admin): CHANGES WHAT THE PAINTING SHOWS. Puts a `ready` character live on a panel of its painting (default: the panel it was created for) - character_retire (POST /v1/characters/:id/retire; partner/admin): CHANGES WHAT THE PAINTING SHOWS. Takes a character off the wall (status `retired`) - admin_partner_create (POST /v1/admin/partners; admin): ADMIN. CREATES AN ACCOUNT AND MINTS A SECRET - admin_painting_create (POST /v1/admin/paintings; admin): ADMIN. CREATES A PAINTING AND MINTS A BOX SECRET - admin_studio_token_create (POST /v1/admin/studio-tokens; admin): ADMIN. MINTS A SECRET - admin_fleet (GET /v1/admin/fleet; admin): ADMIN. Read-only - admin_release_publish (POST /v1/admin/releases; admin): ADMIN. CHANGES WHAT EVERY BOX ON THE CHANNEL RUNS - admin_rollout (POST /v1/admin/paintings/:id/channel; admin): ADMIN. CHANGES WHAT ONE BOX RUNS - admin_character_pull (POST /v1/admin/characters/:id/pull; admin): ADMIN. KILL SWITCH - admin_box_token_create (POST /v1/admin/paintings/:id/box-token; admin): ADMIN. MINTS A SECRET - billing_checkout (POST /v1/billing/checkout; partner/admin): CREATES A STRIPE CHECKOUT SESSION (no money moves until a person pays on the Stripe page). $100 per painting per month - billing_claim (POST /v1/billing/claim; partner/admin): MINTS A SECRET ONCE. After a paid checkout, exchanges its session_id for the new partner account: returns the partner, its paintings and a partner token (shown once; over REST it also signs this browser in) - billing_portal (POST /v1/billing/portal; partner/admin): Returns a short-lived Stripe customer-portal link where a person updates the card, changes the number of paintings, downloads invoices or cancels. Creating the link changes nothing by itself - billing_status (GET /v1/billing; partner/admin): Read-only. Plan (partner = $0 display partner, paid = $100/painting/month), Stripe subscription status, current period end, whether it cancels at period end, paintings covered vs paintings registered, the monthly total, whether a billing portal exists, and whether the paintings are suspended for non-payment - admin_painting_display (POST /v1/admin/paintings/:id/display; admin): ADMIN. CHANGES WHAT THE WALL SHOWS - mind_state (GET /v1/mind/state; studio/admin): STUDIO/ADMIN. Read-only - mind_intent (POST /v1/mind/intent; studio/admin): STUDIO/ADMIN. CHANGES WHAT THE CHARACTERS WANT - admin_painting_delete (POST /v1/admin/paintings/:id/delete; admin): ADMIN. DESTRUCTIVE, NOT REVERSIBLE - admin_partner_delete (POST /v1/admin/partners/:id/delete; admin): ADMIN. DESTRUCTIVE, NOT REVERSIBLE - admin_release_yank (POST /v1/admin/releases/yank; admin): ADMIN. CHANGES WHAT BOXES ON THE CHANNEL RUN - admin_tokens_list (GET /v1/admin/tokens; admin): ADMIN. Read-only - admin_token_revoke (POST /v1/admin/tokens/revoke; admin): ADMIN. REVOKES ACCESS IMMEDIATELY - box_heartbeat (POST /v1/box/heartbeat; box): BOX ONLY. Reports the painting's live state every 30 s: runtime version, installed bundles, per-panel agent state (pose label, goal, mood, dwell, last said) and new journal lines since the last beat (deduplicated by jid, so retries are safe) - box_desired (GET /v1/box/desired; box): BOX ONLY. Read-only - studio_jobs (GET /v1/studio/jobs; studio/admin): STUDIO ONLY. Read-only - studio_job_update (POST /v1/studio/jobs/:id; studio/admin): STUDIO ONLY. CHANGES JOB AND CHARACTER STATUS - studio_bundle_register (POST /v1/studio/bundles; studio/admin): STUDIO ONLY. CHANGES CHARACTER STATUS TO READY - box artifact (GET /v1/box/artifact/; box): stream a release or bundle listed by box_desired, manifest first, then the zip it names. - uploads (PUT /v1/admin/artifacts/, PUT /v1/studio/artifacts/; /upload/ is an alias): raw bytes into storage, zip first then the signed manifest.json, before admin_release_publish / studio_bundle_register.