---
title: "Upload a baseline version"
method: POST
path: "/api/v1/baselines"
tags: ["Baselines"]
---

# Upload a baseline version

`POST /api/v1/baselines`

## Request

- Base URL: `https://dungbeetle.dev`
- URL: `https://dungbeetle.dev/api/v1/baselines`
- Auth: one of:
  - HTTP basic
  - HTTP bearer

Stores a new version for the target, or dedupes (200) when the upload matches the latest version's digest. Requires the `baselines:write` scope on agent tokens.

## Request body

- BaselineUploadPayload
  - `target` string, required
  - `kind` string, required
  - `snapshot` string, required: Canonical baseline JSON, transmitted verbatim as a string.
  - `screenshot` string: Optional base64-encoded PNG.

## Response `200`

Unchanged — matched the latest version (deduped).

- BaselineUploadResponse
  - `deduped` boolean, required: True when the upload matched the latest version's digest.
  - `baseline` BaselineVersion, required
    - `id` string, required
    - `repositoryId` string, required
    - `target` string, required
    - `kind` string, required
    - `version` integer, required
    - `digest` string, required
    - `hasScreenshot` boolean, required
    - `createdAt` string, required

## Other responses

- `201`: New version created.
- `400`: Invalid body or parameter (`code: validation_error`), or — on screenshot upload — a body that does not hash to the digest (`code: digest_mismatch`).
- `401`: Missing/malformed Authorization header (`code: unauthorized`), bad Basic credentials (`code: invalid_credentials`), or an invalid, expired, or revoked agent token (`code: invalid_agent_token`).
- `402`: The owning account is over a hard plan limit or its subscription is paused (`code: billing_blocked`). Existing data is preserved; writes resume after upgrading or freeing space.
- `403`: Agent token outside its granted scopes (`code: missing_scope`, with a `scope` field naming the required scope) or a route that is not agent-accessible at all (`code: agent_forbidden`). Basic-auth requests never see this.
- `413`: Request body exceeds the configured limit (default 25 MiB) (`code: payload_too_large`).
- `429`: Too many failed attempts or uploads from this client (`code: rate_limited`). Honor the `Retry-After` header; successful authenticated requests never count toward the limit.

---

[API](https://skmtc.dev/dungbeetle/apis/dungbeetle-cloud-api.md) · [All operations](https://skmtc.dev/dungbeetle/apis/dungbeetle-cloud-api/llms.txt) · [OpenAPI document](https://skmtc.dev/dungbeetle/apis/dungbeetle-cloud-api/revisions/74778b90420a?raw)