{"openapi":"3.1.0","info":{"title":"Scallywag API","version":"1.1.0","description":"Fetch hand-curated agent personas and their prompts."},"servers":[{"url":"/api/v1"}],"paths":{"/personas":{"get":{"operationId":"listPersonas","summary":"List personas","parameters":[{"name":"style","in":"query","schema":{"type":"string"},"description":"Comma-separated styles: sunny, proper, deadpan, cosy, grand, nerdy, chaotic."},{"name":"vibe","in":"query","schema":{"type":"string"},"deprecated":true,"description":"Old name for `style`."},{"name":"temper","in":"query","schema":{"type":"string"},"description":"Comma-separated: calm, warm, spicy."},{"name":"good_for","in":"query","schema":{"type":"string"},"description":"Comma-separated."},{"name":"source","in":"query","schema":{"type":"string"},"description":"original, classic, licensed."},{"name":"q","in":"query","schema":{"type":"string"},"description":"Free-text search."},{"name":"sort","in":"query","schema":{"type":"string","enum":["loved","newest","az"]}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":24}}],"responses":{"200":{"description":"A page of personas.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonaList"}}}},"400":{"description":"Invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/personas/random":{"get":{"operationId":"randomPersona","summary":"A random persona (optionally filtered)","parameters":[{"name":"style","in":"query","schema":{"type":"string"},"description":"Comma-separated styles: sunny, proper, deadpan, cosy, grand, nerdy, chaotic."},{"name":"vibe","in":"query","schema":{"type":"string"},"deprecated":true,"description":"Old name for `style`."},{"name":"temper","in":"query","schema":{"type":"string"},"description":"Comma-separated: calm, warm, spicy."},{"name":"good_for","in":"query","schema":{"type":"string"},"description":"Comma-separated."},{"name":"source","in":"query","schema":{"type":"string"},"description":"original, classic, licensed."}],"responses":{"200":{"description":"A persona.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Persona"}}}},"404":{"description":"No persona matches the filters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/categories":{"get":{"operationId":"listCategories","summary":"Job categories, with live status, allowed vibes and member counts","responses":{"200":{"description":"Categories, plus the virtual surprise-me."},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/categories/{slug}":{"get":{"operationId":"getCategory","summary":"A category with its members (primary members first) and cameos","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The category and its members."},"404":{"description":"No such category.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/categories/{slug}/random":{"get":{"operationId":"drawPersona","summary":"Meet a persona for this job: sticky per session for 24 hours, no repeats for identified callers","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"A live category, or surprise-me."},{"name":"vibe","in":"query","schema":{"type":"string"},"description":"Comma-separated calm, warm, spicy. Must overlap the category's allowed vibes."},{"name":"session","in":"query","schema":{"type":"string","minLength":8,"maxLength":128},"description":"Keeps the same persona for this key and category for 24 hours."},{"name":"cameo","in":"query","schema":{"type":"string"},"description":"A cameo character to append."},{"name":"reroll","in":"query","schema":{"type":"string","enum":["1"]},"description":"Draw someone other than the session's current persona."},{"name":"intensity","in":"query","schema":{"type":"string","enum":["pinch","full"],"default":"full"}}],"responses":{"200":{"description":"{ persona, category, prompt, reanchor, assignment, pinnedUrl }. Append reanchor after the chat history if you can."},"400":{"description":"Impossible vibe filter (names the allowed vibes) or a bad cameo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No live category with that slug.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"No persona is available right now.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/favorites":{"post":{"operationId":"keepPersona","summary":"Keep a persona (needs an account or an API key)","responses":{"201":{"description":"Saved."},"401":{"description":"Not signed in.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such persona.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/personas/{slug}":{"get":{"operationId":"getPersona","summary":"Get a persona","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"A persona with its full spec.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Persona"}}}},"404":{"description":"Unknown slug.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/personas/{slug}/prompt":{"get":{"operationId":"getPrompt","summary":"Get a rendered prompt","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","schema":{"type":"string","enum":["system","agents_md","skill","json"],"default":"system"}},{"name":"intensity","in":"query","schema":{"type":"string","enum":["pinch","full"],"default":"full"}}],"responses":{"200":{"description":"The prompt text (or JSON for format=json).","headers":{"X-Scallywag-Revision":{"description":"Identifies exactly which revision of the character was served (12 hex chars).","schema":{"type":"string"}},"Repr-Digest":{"description":"RFC 9530 SHA-256 of the body, e.g. sha-256=:base64:. Compare with published advisories.","schema":{"type":"string"}},"ETag":{"description":"Hex SHA-256 of the body.","schema":{"type":"string"}}},"content":{"text/plain":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown slug.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["not_found","invalid_param","rate_limited","internal_error"]},"message":{"type":"string"}}}}},"Persona":{"type":"object","required":["slug","name","logline","tagline","says","avatar","style","vibe","temper","energy","categories","revision"],"properties":{"slug":{"type":"string"},"name":{"type":"string"},"logline":{"type":"string","description":"One or two sentences in the character's voice, to the user."},"tagline":{"type":"string","deprecated":true,"description":"Same as `logline` (characters no longer have a tagline)."},"style":{"type":"string","enum":["sunny","proper","deadpan","cosy","grand","nerdy","chaotic"]},"vibe":{"type":"string","deprecated":true,"description":"Same as `style`. In API v2 `vibe` will mean `temper`."},"temper":{"type":"string","enum":["calm","warm","spicy"]},"energy":{"type":"integer","minimum":1,"maximum":5,"description":"How loud the character is."},"categories":{"type":"array","items":{"type":"string"},"description":"The jobs this character is cast for (code, write, ...)."},"goodFor":{"type":"array","items":{"type":"string"},"description":"Derived from categories."},"source":{"type":"object"},"tags":{"type":"array","items":{"type":"string"}},"flavour":{"type":"object"},"says":{"type":"string","deprecated":true,"description":"Same as `logline`."},"voiceFont":{"type":"string","enum":["serif","grotesque","mono"],"description":"Font the site uses for their quotes."},"avatar":{"type":"object","required":["url","alt"],"properties":{"url":{"type":"string","format":"uri","description":"Absolute URL of a square portrait (512 px)."},"alt":{"type":"string","description":"Alt text describing the picture."}}},"revision":{"type":"string"},"spec":{"type":"object","description":"Full persona spec (single-persona endpoints only)."}}},"PersonaList":{"type":"object","required":["items","nextCursor"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Persona"}},"nextCursor":{"type":["string","null"]}}}}}}