---
title: "Bulk Import Votes"
method: POST
path: "/api/v1/votes/bulk"
tags: ["Votes"]
---

# Bulk Import Votes

`POST /api/v1/votes/bulk`

## Request

- Base URL: `https://app.aimrank.io` (the document declares no server; this is the origin it was published from)
- URL: `https://app.aimrank.io/api/v1/votes/bulk`
- Auth: API key in header `X-API-Key`

Bulk-import votes for a ranking.

Designed for the AI-lab pilot use case: a buyer arrives with a
pre-collected dataset of 10K preference pairs (DPO format, Anthropic
HH format, OpenAssistant pairs) and needs to land them on AimRank
so the rating math + κ + competition report run against their data.
Hitting POST /votes one at a time at the 100/min rate limit takes
~100 minutes; this endpoint takes seconds.

Auth: API key OR JWT — caller must own the ranking. Anonymous
callers cannot bulk-import (fraud-control: a bulk endpoint without
auth is a brigading vector).

Limits: 1000 votes per call. Larger imports must chunk client-side.
No rate-limit decorator — the per-call cap IS the rate-limit.

Partial success is normal: invalid items are returned in `errors`
so the caller can re-submit just the failures.

## Request body

- BulkVoteRequest
  - `ranking_id` string, required
  - `votes` BulkVoteItem[], required: Up to 1000 votes per call
    - `entity_a_id` string, required
    - `entity_b_id` string, required
    - `winner_id` string, nullable
    - `confidence` number, nullable
    - `decision_time_ms` integer, nullable
    - `voter_id` string, nullable: External annotator ID — preserved on the vote for κ analysis
    - `voter_segment` object, nullable

## Response `201`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

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