---
title: "Create End User Agent"
method: POST
path: "/api/v1/end-users/{external_id}/agents"
tags: ["end-users"]
---

# Create End User Agent

`POST /api/v1/end-users/{external_id}/agents`

## Request

- Base URL: `https://api.maritime.sh` (the document declares no server; this is the origin it was published from)
- URL: `https://api.maritime.sh/api/v1/end-users/{external_id}/agents`
- Auth: HTTP bearer

Creates the end user's agent, exactly once.

Upserts the end user, then: when it already has an agent, returns that
agent with 200 and creates nothing; otherwise creates the agent through
the core create path (same gates, same deploy), links it to the end user,
applies the policy, and answers 201. Safe to call on every sign-in.

## Path parameters

- `external_id` string, required

## Request body

- EndUserAgentCreate: Body of ``POST /api/v1/end-users/{external_id}/agents``. The same fields as an agent create. ``name`` may be left out; the end user's external id then names the agent. ``externalId`` is ignored: the path names the end user.
  - `name` string, nullable
  - `description` string, nullable
  - `externalId` string, nullable
  - `instructions` string, nullable
  - `framework` string
  - `tier` string
  - `memMb` integer, nullable
  - `vcpus` number, nullable
  - `idleTtlSeconds` integer, nullable
  - `diskGb` number, nullable
  - `computeMinutesLimit` number, nullable
  - `githubRepo` string, nullable
  - `branch` string, nullable
  - `imageName` string, nullable
  - `templateId` string, nullable
  - `autoPair` boolean
  - `gatewayPassword` string, nullable
  - `serverId` string, nullable
  - `initialEnvVars` InitialEnvVar[]
    - `key` string, required
    - `value` string, required
    - `isSecret` boolean
  - `useMaritimeLlm` boolean
  - `exposedPort` integer, nullable
  - `healthCheckPath` string, nullable
  - `hasWebUi` boolean
  - `publicWeb` boolean
  - `desktop` boolean
  - `uploadS3Key` string, nullable
  - `addOns` string[]
  - `network` object, nullable

## Response `201`

Successful Response

- AgentResponse
  - `id` string, required
  - `name` string, required
  - `description` string, nullable
  - `instructions` string, nullable
  - `externalId` string, nullable
  - `framework` string, required
  - `tier` string, required
  - `status` string, required
  - `githubRepo` string, nullable
  - `autoPair` boolean
  - `exposedPort` integer, nullable
  - `healthCheckPath` string, nullable
  - `hasWebUi` boolean
  - `templateId` string, nullable
  - `publicPlay` boolean
  - `publicWeb` boolean
  - `publicUrl` string, nullable
  - `visibility` 'private' | 'public'
  - `webUrl` string, nullable
  - `desktopEnabled` boolean
  - `invocationCount` integer, required
  - `totalComputeSeconds` integer
  - `memMb` integer, nullable
  - `vcpus` number, nullable
  - `idleTtlSeconds` integer, nullable
  - `diskMb` integer, nullable
  - `computeMinutesLimit` number, nullable
  - `sleepPolicy` string
  - `lastStartedAt` string, date-time, nullable
  - `lastActiveAt` string, date-time, nullable
  - `statusChangedAt` string, date-time, nullable
  - `derivedImageTag` string, nullable
  - `browserbaseConfigured` boolean
  - `projectId` string, nullable
  - `projectRole` string, nullable
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/maritime/apis/maritime-api.md) - [All operations](https://skmtc.dev/maritime/apis/maritime-api/llms.txt) - [OpenAPI document](https://skmtc.dev/maritime/apis/maritime-api/revisions/acd712090ad6?raw)