POST /agents — provision a new Masker proxy agent

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

string

required

Display name for the agent. Must be unique within your account. 1–64 characters.

string

required

Upstream LLM provider and model. Accepted values: openai:gpt-4o-mini, openai:gpt-4o, stub (for testing).

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.

string

default:"healthcare-default"

Name of an existing masking policy to apply. Mutually exclusive with policy_yaml. Defaults to healthcare-default.

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.

object

required

The newly created agent.

Hide agent object fields

string

required

Agent ID in agt_* ULID format.

string

required

Display name as provided.

string

required

Configured upstream LLM.

string

required

Active tokenization scheme.

string

required

Name of the active masking policy.

number

required

Version number of the active policy.

string

required

OpenAI-compatible proxy URL. Set this as your voice platform’s custom LLM endpoint.

string

required

Vapi assistant-request webhook URL. Set this as your Vapi assistant’s server URL.

string

required

ISO 8601 UTC creation timestamp.

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

Status	Code	Meaning
`401`	`unauthenticated`	Missing or invalid `masker_session` cookie
`409`	`name_taken`	An agent with this name already exists in your account
`422`	`validation_failed`	Request body failed validation; see `details` in the error response
`422`	`unknown_upstream`	The `upstream` value does not match a configured provider
`422`	`unknown_policy`	The `policy_name` does not exist
`422`	`policy_yaml_invalid`	The inline `policy_yaml` failed schema validation

Overview

Agents

Sessions

Proxy & Webhooks

POST /agents — provision a new Masker proxy agent

Endpoint

Request body

Response fields

Example

Errors

​Endpoint

​Request body

​Response fields

​Example

​Errors

Endpoint

Request body

Response fields

Example

Errors