# Services

## List services

> List services in a workspace with pagination. Requires \`Service.view\` permission.

```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_ServiceResponse_":{"properties":{"items":{"items":{"$ref":"#/components/schemas/ServiceResponse"},"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[ServiceResponse]"},"ServiceResponse":{"properties":{"id":{"type":"string","title":"Id"},"workspace_id":{"type":"string","title":"Workspace Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"agent_id":{"type":"string","title":"Agent Id"},"context_graph_id":{"type":"string","title":"Context Graph Id"},"agent_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Name"},"context_graph_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Context Graph Name"},"persona_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Persona Name"},"keyterms":{"items":{"type":"string"},"type":"array","title":"Keyterms"},"is_active":{"type":"boolean","title":"Is Active"},"version_sets":{"additionalProperties":{"$ref":"#/components/schemas/VersionSet"},"type":"object","title":"Version Sets"},"tags":{"items":{"$ref":"#/components/schemas/ServiceTag"},"type":"array","title":"Tags"},"tool_capacity":{"type":"integer","title":"Tool Capacity"},"safety_filters_enabled":{"type":"boolean","title":"Safety Filters Enabled","default":true},"channel_type":{"type":"string","enum":["voice","text","scribe"],"title":"Channel Type","default":"voice"},"environment":{"type":"string","enum":["sandbox","production"],"title":"Environment","default":"production"},"voice_config":{"anyOf":[{"$ref":"#/components/schemas/ServiceVoiceConfig"},{"type":"null"}]},"persona_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Persona Id"},"is_system":{"type":"boolean","title":"Is System","default":false},"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","description","agent_id","context_graph_id","keyterms","is_active","version_sets","tags","tool_capacity","created_at","updated_at"],"title":"ServiceResponse"},"VersionSet":{"properties":{"agent_version_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Agent Version Number"},"context_graph_version_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Context Graph Version Number"},"llm_model_preferences":{"additionalProperties":{"$ref":"#/components/schemas/LLMConfig"},"type":"object","title":"Llm Model Preferences","default":{}}},"type":"object","title":"VersionSet","description":"Pins agent, state machine, and LLM model versions for a service."},"LLMConfig":{"properties":{"llm_name":{"type":"string","title":"Llm Name"},"params":{"additionalProperties":true,"type":"object","title":"Params","default":{}}},"type":"object","required":["llm_name"],"title":"LLMConfig"},"ServiceTag":{"properties":{"key":{"type":"string","title":"Key"},"value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Value"}},"type":"object","required":["key"],"title":"ServiceTag"},"ServiceVoiceConfig":{"properties":{"tts_model":{"anyOf":[{"type":"string","enum":["sonic-turbo","sonic-3"]},{"type":"null"}],"title":"Tts Model"},"max_buffer_delay_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Buffer Delay Ms"},"eager_eot_threshold":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Eager Eot Threshold"},"eot_timeout_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Eot Timeout Ms"},"filler_style":{"type":"string","enum":["backchannel","phrase","silent"],"title":"Filler Style","default":"backchannel"},"filler_vocabulary":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Filler Vocabulary"},"backchannel_delay_ms":{"type":"integer","title":"Backchannel Delay Ms","default":400},"max_response_sentences":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Response Sentences"},"max_response_words":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Response Words"},"barge_in_min_speech_s":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Barge In Min Speech S"},"barge_in_cooldown_s":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Barge In Cooldown S"},"forward_call_enabled":{"type":"boolean","title":"Forward Call Enabled","default":false}},"type":"object","title":"ServiceVoiceConfig","description":"Per-service voice pipeline tuning. Overrides workspace/env defaults.\n\nEach field is optional — None means inherit from the layer above\n(workspace VoiceSettings → env vars → hardcoded defaults)."},"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}/services":{"get":{"tags":["Services"],"summary":"List services","description":"List services in a workspace with pagination. Requires `Service.view` permission.","operationId":"list-services","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":"is_active","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Active"}},{"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_ServiceResponse_"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"Not found."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Create a service

> Create a new service linking an agent and HSM. Validates that agent\_id and context\_graph\_id exist in the workspace. Requires \`Service.create\` permission.

```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":{"CreateServiceRequest":{"properties":{"name":{"$ref":"#/components/schemas/NameString"},"description":{"$ref":"#/components/schemas/DescriptionString","default":""},"agent_id":{"type":"string","format":"uuid","title":"Agent Id"},"context_graph_id":{"type":"string","format":"uuid","title":"Context Graph Id"},"keyterms":{"items":{"type":"string"},"type":"array","title":"Keyterms","default":[]},"is_active":{"type":"boolean","title":"Is Active","default":true},"version_sets":{"additionalProperties":{"$ref":"#/components/schemas/VersionSet"},"type":"object","title":"Version Sets","default":{}},"tags":{"items":{"$ref":"#/components/schemas/ServiceTag"},"type":"array","title":"Tags","default":[]},"tool_capacity":{"type":"integer","maximum":10,"minimum":1,"title":"Tool Capacity","default":3},"safety_filters_enabled":{"type":"boolean","title":"Safety Filters Enabled","default":true},"channel_type":{"type":"string","enum":["voice","text","scribe"],"title":"Channel Type","default":"voice"},"environment":{"type":"string","enum":["sandbox","production"],"title":"Environment","default":"production"},"persona_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Persona Id"},"voice_config":{"anyOf":[{"$ref":"#/components/schemas/ServiceVoiceConfig"},{"type":"null"}]}},"type":"object","required":["name","agent_id","context_graph_id"],"title":"CreateServiceRequest"},"NameString":{"type":"string","maxLength":256,"minLength":1},"DescriptionString":{"type":"string","maxLength":2000},"VersionSet":{"properties":{"agent_version_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Agent Version Number"},"context_graph_version_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Context Graph Version Number"},"llm_model_preferences":{"additionalProperties":{"$ref":"#/components/schemas/LLMConfig"},"type":"object","title":"Llm Model Preferences","default":{}}},"type":"object","title":"VersionSet","description":"Pins agent, state machine, and LLM model versions for a service."},"LLMConfig":{"properties":{"llm_name":{"type":"string","title":"Llm Name"},"params":{"additionalProperties":true,"type":"object","title":"Params","default":{}}},"type":"object","required":["llm_name"],"title":"LLMConfig"},"ServiceTag":{"properties":{"key":{"type":"string","title":"Key"},"value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Value"}},"type":"object","required":["key"],"title":"ServiceTag"},"ServiceVoiceConfig":{"properties":{"tts_model":{"anyOf":[{"type":"string","enum":["sonic-turbo","sonic-3"]},{"type":"null"}],"title":"Tts Model"},"max_buffer_delay_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Buffer Delay Ms"},"eager_eot_threshold":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Eager Eot Threshold"},"eot_timeout_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Eot Timeout Ms"},"filler_style":{"type":"string","enum":["backchannel","phrase","silent"],"title":"Filler Style","default":"backchannel"},"filler_vocabulary":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Filler Vocabulary"},"backchannel_delay_ms":{"type":"integer","title":"Backchannel Delay Ms","default":400},"max_response_sentences":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Response Sentences"},"max_response_words":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Response Words"},"barge_in_min_speech_s":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Barge In Min Speech S"},"barge_in_cooldown_s":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Barge In Cooldown S"},"forward_call_enabled":{"type":"boolean","title":"Forward Call Enabled","default":false}},"type":"object","title":"ServiceVoiceConfig","description":"Per-service voice pipeline tuning. Overrides workspace/env defaults.\n\nEach field is optional — None means inherit from the layer above\n(workspace VoiceSettings → env vars → hardcoded defaults)."},"ServiceResponse":{"properties":{"id":{"type":"string","title":"Id"},"workspace_id":{"type":"string","title":"Workspace Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"agent_id":{"type":"string","title":"Agent Id"},"context_graph_id":{"type":"string","title":"Context Graph Id"},"agent_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Name"},"context_graph_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Context Graph Name"},"persona_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Persona Name"},"keyterms":{"items":{"type":"string"},"type":"array","title":"Keyterms"},"is_active":{"type":"boolean","title":"Is Active"},"version_sets":{"additionalProperties":{"$ref":"#/components/schemas/VersionSet"},"type":"object","title":"Version Sets"},"tags":{"items":{"$ref":"#/components/schemas/ServiceTag"},"type":"array","title":"Tags"},"tool_capacity":{"type":"integer","title":"Tool Capacity"},"safety_filters_enabled":{"type":"boolean","title":"Safety Filters Enabled","default":true},"channel_type":{"type":"string","enum":["voice","text","scribe"],"title":"Channel Type","default":"voice"},"environment":{"type":"string","enum":["sandbox","production"],"title":"Environment","default":"production"},"voice_config":{"anyOf":[{"$ref":"#/components/schemas/ServiceVoiceConfig"},{"type":"null"}]},"persona_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Persona Id"},"is_system":{"type":"boolean","title":"Is System","default":false},"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","description","agent_id","context_graph_id","keyterms","is_active","version_sets","tags","tool_capacity","created_at","updated_at"],"title":"ServiceResponse"}}},"paths":{"/v1/{workspace_id}/services":{"post":{"tags":["Services"],"summary":"Create a service","description":"Create a new service linking an agent and HSM. Validates that agent_id and context_graph_id exist in the workspace. Requires `Service.create` permission.","operationId":"create-service","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateServiceRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceResponse"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"Not found."},"409":{"description":"Name already taken."},"422":{"description":"Invalid request body."}}}}}}
```

## Get a service

> Retrieve a service by ID. Requires \`Service.view\` permission.

```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":{"ServiceResponse":{"properties":{"id":{"type":"string","title":"Id"},"workspace_id":{"type":"string","title":"Workspace Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"agent_id":{"type":"string","title":"Agent Id"},"context_graph_id":{"type":"string","title":"Context Graph Id"},"agent_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Name"},"context_graph_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Context Graph Name"},"persona_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Persona Name"},"keyterms":{"items":{"type":"string"},"type":"array","title":"Keyterms"},"is_active":{"type":"boolean","title":"Is Active"},"version_sets":{"additionalProperties":{"$ref":"#/components/schemas/VersionSet"},"type":"object","title":"Version Sets"},"tags":{"items":{"$ref":"#/components/schemas/ServiceTag"},"type":"array","title":"Tags"},"tool_capacity":{"type":"integer","title":"Tool Capacity"},"safety_filters_enabled":{"type":"boolean","title":"Safety Filters Enabled","default":true},"channel_type":{"type":"string","enum":["voice","text","scribe"],"title":"Channel Type","default":"voice"},"environment":{"type":"string","enum":["sandbox","production"],"title":"Environment","default":"production"},"voice_config":{"anyOf":[{"$ref":"#/components/schemas/ServiceVoiceConfig"},{"type":"null"}]},"persona_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Persona Id"},"is_system":{"type":"boolean","title":"Is System","default":false},"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","description","agent_id","context_graph_id","keyterms","is_active","version_sets","tags","tool_capacity","created_at","updated_at"],"title":"ServiceResponse"},"VersionSet":{"properties":{"agent_version_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Agent Version Number"},"context_graph_version_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Context Graph Version Number"},"llm_model_preferences":{"additionalProperties":{"$ref":"#/components/schemas/LLMConfig"},"type":"object","title":"Llm Model Preferences","default":{}}},"type":"object","title":"VersionSet","description":"Pins agent, state machine, and LLM model versions for a service."},"LLMConfig":{"properties":{"llm_name":{"type":"string","title":"Llm Name"},"params":{"additionalProperties":true,"type":"object","title":"Params","default":{}}},"type":"object","required":["llm_name"],"title":"LLMConfig"},"ServiceTag":{"properties":{"key":{"type":"string","title":"Key"},"value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Value"}},"type":"object","required":["key"],"title":"ServiceTag"},"ServiceVoiceConfig":{"properties":{"tts_model":{"anyOf":[{"type":"string","enum":["sonic-turbo","sonic-3"]},{"type":"null"}],"title":"Tts Model"},"max_buffer_delay_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Buffer Delay Ms"},"eager_eot_threshold":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Eager Eot Threshold"},"eot_timeout_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Eot Timeout Ms"},"filler_style":{"type":"string","enum":["backchannel","phrase","silent"],"title":"Filler Style","default":"backchannel"},"filler_vocabulary":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Filler Vocabulary"},"backchannel_delay_ms":{"type":"integer","title":"Backchannel Delay Ms","default":400},"max_response_sentences":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Response Sentences"},"max_response_words":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Response Words"},"barge_in_min_speech_s":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Barge In Min Speech S"},"barge_in_cooldown_s":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Barge In Cooldown S"},"forward_call_enabled":{"type":"boolean","title":"Forward Call Enabled","default":false}},"type":"object","title":"ServiceVoiceConfig","description":"Per-service voice pipeline tuning. Overrides workspace/env defaults.\n\nEach field is optional — None means inherit from the layer above\n(workspace VoiceSettings → env vars → hardcoded defaults)."},"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}/services/{service_id}":{"get":{"tags":["Services"],"summary":"Get a service","description":"Retrieve a service by ID. Requires `Service.view` permission.","operationId":"get-service","parameters":[{"name":"service_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Service Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceResponse"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"Not found."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Update a service

> Update a service's configuration. Requires \`Service.update\` permission.

```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":{"UpdateServiceRequest":{"properties":{"name":{"anyOf":[{"$ref":"#/components/schemas/NameString"},{"type":"null"}]},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"agent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Agent Id"},"context_graph_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Context Graph Id"},"keyterms":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Keyterms"},"is_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Active"},"version_sets":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/VersionSet"},"type":"object"},{"type":"null"}],"title":"Version Sets"},"tags":{"anyOf":[{"items":{"$ref":"#/components/schemas/ServiceTag"},"type":"array"},{"type":"null"}],"title":"Tags"},"tool_capacity":{"anyOf":[{"type":"integer","maximum":10,"minimum":1},{"type":"null"}],"title":"Tool Capacity"},"safety_filters_enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Safety Filters Enabled"},"channel_type":{"anyOf":[{"type":"string","enum":["voice","text","scribe"]},{"type":"null"}],"title":"Channel Type"},"environment":{"anyOf":[{"type":"string","enum":["sandbox","production"]},{"type":"null"}],"title":"Environment"},"persona_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Persona Id"},"voice_config":{"anyOf":[{"$ref":"#/components/schemas/ServiceVoiceConfig"},{"type":"null"}]}},"type":"object","title":"UpdateServiceRequest"},"NameString":{"type":"string","maxLength":256,"minLength":1},"DescriptionString":{"type":"string","maxLength":2000},"VersionSet":{"properties":{"agent_version_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Agent Version Number"},"context_graph_version_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Context Graph Version Number"},"llm_model_preferences":{"additionalProperties":{"$ref":"#/components/schemas/LLMConfig"},"type":"object","title":"Llm Model Preferences","default":{}}},"type":"object","title":"VersionSet","description":"Pins agent, state machine, and LLM model versions for a service."},"LLMConfig":{"properties":{"llm_name":{"type":"string","title":"Llm Name"},"params":{"additionalProperties":true,"type":"object","title":"Params","default":{}}},"type":"object","required":["llm_name"],"title":"LLMConfig"},"ServiceTag":{"properties":{"key":{"type":"string","title":"Key"},"value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Value"}},"type":"object","required":["key"],"title":"ServiceTag"},"ServiceVoiceConfig":{"properties":{"tts_model":{"anyOf":[{"type":"string","enum":["sonic-turbo","sonic-3"]},{"type":"null"}],"title":"Tts Model"},"max_buffer_delay_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Buffer Delay Ms"},"eager_eot_threshold":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Eager Eot Threshold"},"eot_timeout_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Eot Timeout Ms"},"filler_style":{"type":"string","enum":["backchannel","phrase","silent"],"title":"Filler Style","default":"backchannel"},"filler_vocabulary":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Filler Vocabulary"},"backchannel_delay_ms":{"type":"integer","title":"Backchannel Delay Ms","default":400},"max_response_sentences":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Response Sentences"},"max_response_words":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Response Words"},"barge_in_min_speech_s":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Barge In Min Speech S"},"barge_in_cooldown_s":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Barge In Cooldown S"},"forward_call_enabled":{"type":"boolean","title":"Forward Call Enabled","default":false}},"type":"object","title":"ServiceVoiceConfig","description":"Per-service voice pipeline tuning. Overrides workspace/env defaults.\n\nEach field is optional — None means inherit from the layer above\n(workspace VoiceSettings → env vars → hardcoded defaults)."},"ServiceResponse":{"properties":{"id":{"type":"string","title":"Id"},"workspace_id":{"type":"string","title":"Workspace Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"agent_id":{"type":"string","title":"Agent Id"},"context_graph_id":{"type":"string","title":"Context Graph Id"},"agent_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Name"},"context_graph_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Context Graph Name"},"persona_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Persona Name"},"keyterms":{"items":{"type":"string"},"type":"array","title":"Keyterms"},"is_active":{"type":"boolean","title":"Is Active"},"version_sets":{"additionalProperties":{"$ref":"#/components/schemas/VersionSet"},"type":"object","title":"Version Sets"},"tags":{"items":{"$ref":"#/components/schemas/ServiceTag"},"type":"array","title":"Tags"},"tool_capacity":{"type":"integer","title":"Tool Capacity"},"safety_filters_enabled":{"type":"boolean","title":"Safety Filters Enabled","default":true},"channel_type":{"type":"string","enum":["voice","text","scribe"],"title":"Channel Type","default":"voice"},"environment":{"type":"string","enum":["sandbox","production"],"title":"Environment","default":"production"},"voice_config":{"anyOf":[{"$ref":"#/components/schemas/ServiceVoiceConfig"},{"type":"null"}]},"persona_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Persona Id"},"is_system":{"type":"boolean","title":"Is System","default":false},"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","description","agent_id","context_graph_id","keyterms","is_active","version_sets","tags","tool_capacity","created_at","updated_at"],"title":"ServiceResponse"}}},"paths":{"/v1/{workspace_id}/services/{service_id}":{"put":{"tags":["Services"],"summary":"Update a service","description":"Update a service's configuration. Requires `Service.update` permission.","operationId":"update-service","parameters":[{"name":"service_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Service Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateServiceRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceResponse"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"Not found."},"409":{"description":"Name already taken."},"422":{"description":"Invalid request body."}}}}}}
```

## Delete a service

> Delete a service. Requires \`Service.delete\` permission.

```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}/services/{service_id}":{"delete":{"tags":["Services"],"summary":"Delete a service","description":"Delete a service. Requires `Service.delete` permission.","operationId":"delete-service","parameters":[{"name":"service_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Service Id"}}],"responses":{"204":{"description":"Successful Response"},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"Not found."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Upsert a service version set

> Replace or create a named version set on a service. Pinned agent/HSM versions are validated.

```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":{"UpsertVersionSetRequest":{"properties":{"version_set":{"$ref":"#/components/schemas/VersionSet"}},"type":"object","required":["version_set"],"title":"UpsertVersionSetRequest"},"VersionSet":{"properties":{"agent_version_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Agent Version Number"},"context_graph_version_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Context Graph Version Number"},"llm_model_preferences":{"additionalProperties":{"$ref":"#/components/schemas/LLMConfig"},"type":"object","title":"Llm Model Preferences","default":{}}},"type":"object","title":"VersionSet","description":"Pins agent, state machine, and LLM model versions for a service."},"LLMConfig":{"properties":{"llm_name":{"type":"string","title":"Llm Name"},"params":{"additionalProperties":true,"type":"object","title":"Params","default":{}}},"type":"object","required":["llm_name"],"title":"LLMConfig"}}},"paths":{"/v1/{workspace_id}/services/{service_id}/version-sets/{name}":{"put":{"tags":["Services"],"summary":"Upsert a service version set","description":"Replace or create a named version set on a service. Pinned agent/HSM versions are validated.","operationId":"upsert-service-version-set","parameters":[{"name":"service_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Service Id"}},{"name":"name","in":"path","required":true,"schema":{"type":"string","maxLength":40,"description":"Version set name (e.g. 'release')","title":"Name"},"description":"Version set name (e.g. 'release')"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpsertVersionSetRequest"}}}},"responses":{"204":{"description":"Successful Response"},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"Not found."},"409":{"description":"Name already taken."},"422":{"description":"Invalid request body."}}}}}}
```