---
title: "Create an agent config"
method: POST
path: "/agents"
tags: ["agents"]
---

# Create an agent config

`POST /agents`

## Request

- Base URL: `https://api.letsship.ai/v1`
- URL: `https://api.letsship.ai/v1/agents`
- Auth: none declared

## Request body

- CreateAgentRequest
  - `name` string, required
  - `role` 'researcher' | 'planner' | 'builder' | 'reviewer' | 'deployer' | 'tester', required
  - `harness` 'hermes' | 'pi' | 'kilo-code' | 'open-code' | 'claude-code' | 'codex' | 'copilot', required
  - `model` string, required
  - `effort` string
  - `sandbox` union, required
    - object
      - `kind` 'existing', required
      - `templateId` string, required
    - object
      - `kind` 'new', required
      - `template` NewSandboxTemplateInput, required
        - `name` string, required
        - `dockerfile` string, required
        - `size` union
          - 'standard-1' | 'standard-2' | 'standard-3' | 'standard-4'
          - object
            - `vcpu` integer, required
            - `memoryMib` integer, required
            - `diskMb` integer, required
        - `instanceType` 'lite' | 'basic' | 'standard-1' | 'standard-2' | 'standard-3' | 'standard-4'
  - `userPrompt` string: Deprecated: not read by the pipeline; agent instructions and skills are configured in the target repo.
  - `skillRepos` string[]: Deprecated: not read by the pipeline; agent instructions and skills are configured in the target repo.

## Response `200`

Created

- Agent
  - `id` string, required
  - `orgId` string, required
  - `name` string, required
  - `role` 'researcher' | 'planner' | 'builder' | 'reviewer' | 'deployer' | 'tester', required
  - `harness` 'hermes' | 'pi' | 'kilo-code' | 'open-code' | 'claude-code' | 'codex' | 'copilot', required
  - `model` string, required
  - `effort` string, nullable, required
  - `sandboxTemplateId` string, required
  - `userPrompt` string, nullable, required: Deprecated: not read by the pipeline; agent instructions and skills are configured in the target repo.
  - `skillRepos` string[], required: Deprecated: not read by the pipeline; agent instructions and skills are configured in the target repo.
  - `isBuiltin` boolean, required
  - `createdAt` integer, required
  - `updatedAt` integer, required

## Other responses

- `400`: Invalid
- `403`: Role insufficient
- `404`: No org for caller
- `409`: An inline sandbox's name is taken
- `422`: An inline sandbox can't be used
- `503`: Sandbox builds unavailable

---

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