> ## 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.

# POST /agents — provision a new Masker proxy agent

> Provision a new agent with a name, upstream LLM, and tokenization scheme. Returns the proxy and webhook URLs you need for voice platform configuration.

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

<ParamField body="name" type="string" required>
  Display name for the agent. Must be unique within your account. 1–64 characters.
</ParamField>

<ParamField body="upstream" type="string" required>
  Upstream LLM provider and model. Accepted values: `openai:gpt-4o-mini`, `openai:gpt-4o`, `stub` (for testing).
</ParamField>

<ParamField body="tokenization" type="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.
</ParamField>

<ParamField body="policy_name" type="string" default="healthcare-default">
  Name of an existing masking policy to apply. Mutually exclusive with `policy_yaml`. Defaults to `healthcare-default`.
</ParamField>

<ParamField body="policy_yaml" type="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`.
</ParamField>

## Response fields

On success the API returns `201 Created` with the full agent object.

<ResponseField name="agent" type="object" required>
  The newly created agent.

  <Expandable title="agent object fields" defaultOpen>
    <ResponseField name="id" type="string" required>
      Agent ID in `agt_*` ULID format.
    </ResponseField>

    <ResponseField name="name" type="string" required>
      Display name as provided.
    </ResponseField>

    <ResponseField name="upstream" type="string" required>
      Configured upstream LLM.
    </ResponseField>

    <ResponseField name="tokenization" type="string" required>
      Active tokenization scheme.
    </ResponseField>

    <ResponseField name="policy_name" type="string" required>
      Name of the active masking policy.
    </ResponseField>

    <ResponseField name="policy_version" type="number" required>
      Version number of the active policy.
    </ResponseField>

    <ResponseField name="proxy_url" type="string" required>
      OpenAI-compatible proxy URL. Set this as your voice platform's custom LLM endpoint.
    </ResponseField>

    <ResponseField name="webhook_url" type="string" required>
      Vapi assistant-request webhook URL. Set this as your Vapi assistant's server URL.
    </ResponseField>

    <ResponseField name="created_at" type="string" required>
      ISO 8601 UTC creation timestamp.
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

<CodeGroup>
  ```bash curl theme={null}
  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"
    }'
  ```
</CodeGroup>

```json Response (201 Created) theme={null}
{
  "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                   |