---
title: "Create a comparison"
method: POST
path: "/comparisons"
---

# Create a comparison

`POST /comparisons`

## Request

- Base URL: `https://api.agentsky.dev/v1`
- URL: `https://api.agentsky.dev/v1/comparisons`
- Auth: HTTP bearer

Start a new side-by-side comparison: send one task to the main agent and one or more agents in `compare` simultaneously. `requestId` makes a retry safe.

## Request body

- object
  - `requestId` string, required: Idempotency key (16–100 alphanumeric/dash/underscore).
  - `agentType` string, required: The main agent's harness type.
  - `llm` string, required: The main agent's model.
  - `reasoningEffort` string: Optional thinking level for the main agent.
  - `task` string, required: The task text sent to every agent.
  - `compare` object[], required: One or more additional agents to compare against (each with agentType and llm).
    - `agentType` string, required
    - `llm` string, required
    - `reasoningEffort` string
  - `capabilities` string[]: Tool ids to grant every agent (all by default).
  - `timezone` string: IANA timezone for the session.

## Response `201`

Comparison created.

- object
  - `comparisonId` string, required
  - `columns` object[], required
    - `columnId` string
    - `sessionId` string

## Other responses

- `400`: Error — { error: { code, message } }
- `401`: Error — { error: { code, message } }
- `409`: Error — { error: { code, message } }
- `422`: Error — { error: { code, message } }
- `default`: Error — { error: { code, message, request_id } }

## Changes

- **2026-11-02** `e5e8f0229a99`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/agentsky/apis/agentsky-developer-api/changes/comparisons/post.md)

---

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