---
title: "POST /uploads/{id}/factor-agent/analysis/upsert"
method: POST
path: "/uploads/{id}/factor-agent/analysis/upsert"
tags: ["Uploads"]
---

# POST /uploads/{id}/factor-agent/analysis/upsert

`POST /uploads/{id}/factor-agent/analysis/upsert`

## Path parameters

- `id` integer, required

## Request body

- DirectUploadFactorAnalysisUpsertRequest
  - `allItems` object[], required
  - `diagnostics` object[], required
    - `code` string, required
    - `fields` string[], required
    - `itemId` string
    - `message` string, required
    - `severity` 'warning' | 'error', required
  - `filterOptions` object
    - `activityUnits` string[]
    - `regionCodes` string[]
    - `scopes` integer[]
    - `units` string[]
  - `items` DirectUploadFactorAnalysisUpsertItem[], required
    - `candidates` DirectUploadFactorAnalysisUpsertCandidate[], required
      - `activityUnit` string
      - `confidence` 'high' | 'medium' | 'low', required
      - `factorValue` number, double
      - `id` string, required
      - `libraryId` string
      - `libraryName` string
      - `name` string
      - `reason` string, required
      - `regionCode` string
      - `releaseId` string
      - `releaseYear` integer
      - `scope` integer
      - `unit` string
      - `warnings` string[], required
    - `emissionPreview` object
      - `unit` string, required
      - `value` number, double, required
    - `itemId` string, required
    - `itemIndex` integer, required
    - `matchingHints` object, required — Strict matching hints v2 contract.
    - `message` string
    - `selectedFactor` DirectUploadFactorCandidate
      - `activityUnit` string
      - `confidence` 'high' | 'medium' | 'low'
      - `factorValue` number, double
      - `id` string, required
      - `libraryId` string
      - `libraryName` string
      - `name` string, required
      - `reason` string
      - `regionCode` string
      - `releaseId` string
      - `releaseYear` integer
      - `scope` integer
      - `unit` string
      - `warnings` string[]
    - `selectedFactorId` string
    - `sourceRecord` object, required — Strict emission-source-record/v2 contract.
    - `status` 'completed' | 'needs_input', required
  - `message` string, required
  - `schemaVersion` 'direct-upload-factor-review/v2', required
  - `sourceFileSha256` string, required
  - `status` 'completed' | 'needs_input', required
  - `summary` string, required
  - `warnings` string[], required

## Response `200`

Analysis created or replaced with a new version

- DirectUploadFactorAnalysisResponse
  - `data` object, required
    - `allItems` object[], required
    - `confirmationMessage` string
    - `customPrompt` string
    - `extractionProvenance` object
      - `agentVariant` 'legacy' | 'skill_v1'
      - `attemptCount` integer
      - `diagnosticCodes` string[], required
      - `model` string
      - `policyVersion` string
      - `provider` string
      - `traceId` string
    - `items` object[], required
    - `message` string, required
    - `provenance` 'web' | 'cli', required
    - `schemaVersion` 'direct-upload-factor-review/v2', required
    - `sessionId` string
    - `sourceFileSha256` string, required
    - `status` 'processing' | 'completed' | 'needs_input' | 'error', required
    - `submitted` boolean, required
    - `submittedAt` string, date-time
    - `summary` string, required
    - `uploadId` integer, required
    - `userReviewHints` DirectUploadUserReviewHints
      - `itemTypes` object
    - `versionId` string, uuid, required
    - `warnings` string[], required

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `409` — Source file hash does not match the upload

## Changes

- **2026-09-02** `4fccdcaa5e57` — 1 info
  - added the optional property `data/extractionProvenance` to the response with the `200` status

[Change history](https://skmtc.dev/greentally/apis/esgai-api/changes/uploads/:id/factor-agent/analysis/upsert/post.md)

---

[API](https://skmtc.dev/greentally/apis/esgai-api.md) · [All operations](https://skmtc.dev/greentally/apis/esgai-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/greentally/esgai-api/revisions/4fccdcaa5e57/schema)