# Personas

## List personas

> List personas in the workspace.\
> \
> Permissions: viewer+.\
> Search: case-insensitive on name and background.\
> Sort: +name, -name, +created\_at, -created\_at, +updated\_at, -updated\_at.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"SearchString":{"type":"string","maxLength":200,"minLength":1},"PaginatedResponse_PersonaResponse_":{"properties":{"items":{"items":{"$ref":"#/components/schemas/PersonaResponse"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Continuation Token"},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total"}},"type":"object","required":["items","has_more"],"title":"PaginatedResponse[PersonaResponse]"},"PersonaResponse":{"properties":{"id":{"type":"string","title":"Id"},"workspace_id":{"type":"string","title":"Workspace Id"},"name":{"type":"string","title":"Name"},"role":{"type":"string","title":"Role"},"developed_by":{"type":"string","title":"Developed By"},"communication_style":{"additionalProperties":true,"type":"object","title":"Communication Style"},"default_language":{"type":"string","title":"Default Language"},"background":{"type":"string","title":"Background"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","workspace_id","name","role","developed_by","communication_style","default_language","background","created_at","updated_at"],"title":"PersonaResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/personas":{"get":{"tags":["Personas"],"summary":"List personas","description":"List personas in the workspace.\n\nPermissions: viewer+.\nSearch: case-insensitive on name and background.\nSort: +name, -name, +created_at, -created_at, +updated_at, -updated_at.","operationId":"list-personas","parameters":[{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/SearchString"},{"type":"null"}],"title":"Search"}},{"name":"sort_by","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sort By"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":20,"exclusiveMinimum":0,"default":10,"title":"Limit"}},{"name":"continuation_token","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Continuation Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse_PersonaResponse_"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Rate limited"}}}}}}
```

## Create a persona

> Create a new persona.\
> \
> Permissions: admin, owner.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"CreatePersonaRequest":{"properties":{"name":{"$ref":"#/components/schemas/NameString"},"role":{"$ref":"#/components/schemas/NameString"},"developed_by":{"$ref":"#/components/schemas/NameString"},"communication_style":{"additionalProperties":true,"type":"object","title":"Communication Style"},"default_language":{"type":"string","maxLength":10,"title":"Default Language","default":"eng"},"background":{"$ref":"#/components/schemas/DescriptionString","default":""}},"type":"object","required":["name","role","developed_by"],"title":"CreatePersonaRequest"},"NameString":{"type":"string","maxLength":256,"minLength":1},"DescriptionString":{"type":"string","maxLength":2000},"PersonaResponse":{"properties":{"id":{"type":"string","title":"Id"},"workspace_id":{"type":"string","title":"Workspace Id"},"name":{"type":"string","title":"Name"},"role":{"type":"string","title":"Role"},"developed_by":{"type":"string","title":"Developed By"},"communication_style":{"additionalProperties":true,"type":"object","title":"Communication Style"},"default_language":{"type":"string","title":"Default Language"},"background":{"type":"string","title":"Background"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","workspace_id","name","role","developed_by","communication_style","default_language","background","created_at","updated_at"],"title":"PersonaResponse"}}},"paths":{"/v1/{workspace_id}/personas":{"post":{"tags":["Personas"],"summary":"Create a persona","description":"Create a new persona.\n\nPermissions: admin, owner.","operationId":"create-persona","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePersonaRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonaResponse"}}}},"422":{"description":"Validation error"},"429":{"description":"Rate limited"}}}}}}
```

## Get a persona

> Get a persona by ID.\
> \
> Permissions: viewer+.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"PersonaResponse":{"properties":{"id":{"type":"string","title":"Id"},"workspace_id":{"type":"string","title":"Workspace Id"},"name":{"type":"string","title":"Name"},"role":{"type":"string","title":"Role"},"developed_by":{"type":"string","title":"Developed By"},"communication_style":{"additionalProperties":true,"type":"object","title":"Communication Style"},"default_language":{"type":"string","title":"Default Language"},"background":{"type":"string","title":"Background"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","workspace_id","name","role","developed_by","communication_style","default_language","background","created_at","updated_at"],"title":"PersonaResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/personas/{persona_id}":{"get":{"tags":["Personas"],"summary":"Get a persona","description":"Get a persona by ID.\n\nPermissions: viewer+.","operationId":"get-persona","parameters":[{"name":"persona_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Persona Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonaResponse"}}}},"404":{"description":"Persona not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Rate limited"}}}}}}
```

## Delete a persona

> Delete a persona.\
> \
> Permissions: admin, owner.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/personas/{persona_id}":{"delete":{"tags":["Personas"],"summary":"Delete a persona","description":"Delete a persona.\n\nPermissions: admin, owner.","operationId":"delete-persona","parameters":[{"name":"persona_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Persona Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Persona not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Rate limited"}}}}}}
```

## Update a persona

> Update a persona.\
> \
> Permissions: admin, owner.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"UpdatePersonaRequest":{"properties":{"name":{"anyOf":[{"$ref":"#/components/schemas/NameString"},{"type":"null"}]},"role":{"anyOf":[{"$ref":"#/components/schemas/NameString"},{"type":"null"}]},"developed_by":{"anyOf":[{"$ref":"#/components/schemas/NameString"},{"type":"null"}]},"communication_style":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Communication Style"},"default_language":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}],"title":"Default Language"},"background":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]}},"type":"object","title":"UpdatePersonaRequest"},"NameString":{"type":"string","maxLength":256,"minLength":1},"DescriptionString":{"type":"string","maxLength":2000},"PersonaResponse":{"properties":{"id":{"type":"string","title":"Id"},"workspace_id":{"type":"string","title":"Workspace Id"},"name":{"type":"string","title":"Name"},"role":{"type":"string","title":"Role"},"developed_by":{"type":"string","title":"Developed By"},"communication_style":{"additionalProperties":true,"type":"object","title":"Communication Style"},"default_language":{"type":"string","title":"Default Language"},"background":{"type":"string","title":"Background"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","workspace_id","name","role","developed_by","communication_style","default_language","background","created_at","updated_at"],"title":"PersonaResponse"}}},"paths":{"/v1/{workspace_id}/personas/{persona_id}":{"patch":{"tags":["Personas"],"summary":"Update a persona","description":"Update a persona.\n\nPermissions: admin, owner.","operationId":"update-persona","parameters":[{"name":"persona_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Persona Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePersonaRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonaResponse"}}}},"404":{"description":"Persona not found"},"422":{"description":"Validation error"},"429":{"description":"Rate limited"}}}}}}
```