Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.masker.dev/llms.txt

Use this file to discover all available pages before exploring further.

Creates a new agent in your account. After creation, the response includes the proxy_url and webhook_url for the agent — these are the two URLs you configure in your voice platform (e.g. Vapi’s custom LLM URL and server URL fields). The agent is immediately active once created.

​
Endpoint

POST /api/v1/agents
Requires masker_session authentication.

​
Request body

​
name
string
required
Display name for the agent. Must be unique within your account. 1–64 characters.
​
upstream
string
required
Upstream LLM provider and model. Accepted values: openai:gpt-4o-mini, openai:gpt-4o, stub (for testing).
​
tokenization
string
default:"vault-deterministic"
Tokenization scheme to use for PHI replacement tokens. vault-deterministic produces consistent tokens for the same input value (useful for de-duplication and audit correlation). reversible-aead produces encrypted tokens that are reversible without a vault lookup.
​
policy_name
string
default:"healthcare-default"
Name of an existing masking policy to apply. Mutually exclusive with policy_yaml. Defaults to healthcare-default.
​
policy_yaml
string
Inline YAML definition of a custom masking policy. Mutually exclusive with policy_name. The YAML is validated before the agent is created; an invalid policy returns 422.

​
Response fields

On success the API returns 201 Created with the full agent object.
​
agent
object
required
The newly created agent.

​
Example

curl -X POST \
  -H "Cookie: masker_session=ey..." \
  -H "Content-Type: application/json" \
  https://masker-voice.fly.dev/api/v1/agents \
  -d '{
    "name": "appointment-bot-prod",
    "upstream": "openai:gpt-4o-mini",
    "tokenization": "vault-deterministic"
  }'
Response (201 Created)
{
  "agent": {
    "id": "agt_01HYZ...",
    "name": "appointment-bot-prod",
    "upstream": "openai:gpt-4o-mini",
    "tokenization": "vault-deterministic",
    "policy_name": "healthcare-default",
    "policy_version": 1,
    "proxy_url": "https://masker-voice.fly.dev/proxy/agt_01HYZ.../v1/chat/completions",
    "webhook_url": "https://masker-voice.fly.dev/vapi/webhook/agt_01HYZ...",
    "created_at": "2026-05-03T21:14:32Z"
  }
}

​
Errors

StatusCodeMeaning
401unauthenticatedMissing or invalid masker_session cookie
409name_takenAn agent with this name already exists in your account
422validation_failedRequest body failed validation; see details in the error response
422unknown_upstreamThe upstream value does not match a configured provider
422unknown_policyThe policy_name does not exist
422policy_yaml_invalidThe inline policy_yaml failed schema validation