---
title: "Upload one session [write]"
method: PUT
path: "/trace-library/{harness}/{session_id}"
tags: ["trace-library"]
---

# Upload one session \[write\]

`PUT /trace-library/{harness}/{session_id}`

## Request

- Base URL: `https://api.agentsky.dev/v1`
- URL: `https://api.agentsky.dev/v1/trace-library/{harness}/{session_id}`
- Auth: HTTP bearer

Stores the session's messages, redacted again on arrival and cut to 8 KiB each, replacing an earlier version. The same sha256 is a no-op (unchanged). A session another member uploaded answers 409 trace_owned. The body is at most 8 MiB. Workspace keys are refused: uploads and reads belong to a person. Returns 503 not_migrated before the tables exist.

## Path parameters

- `harness` string, required
- `session_id` string, required

## Request body

- object
  - `sha256` string, required: The device's digest of the messages; repeats of it are not stored again
  - `title` string
  - `cwd` string
  - `project` string
  - `git_branch` string
  - `git_commit` string
  - `git_remote` string: The repository URL, without credentials
  - `model` string: The model that answered most
  - `models` string[]: Every model that answered, most-used first
  - `harness_version` string
  - `client` string
  - `model_provider` string
  - `effort` string
  - `usage` object
    - `input_tokens` integer
    - `output_tokens` integer
    - `cache_read_tokens` integer
    - `cache_write_tokens` integer
    - `reasoning_tokens` integer
  - `device` string
  - `started_at` string, date-time
  - `ended_at` string, date-time
  - `user_turns` integer
  - `tool_calls` integer
  - `partial` boolean: The device left messages out to fit
  - `environment` object: The working folder the session ran in, already uploaded as one of your files in this workspace; 400 invalid_environment for a file you cannot see. Fold its file_id into sha256 so linking it later is a changed upload.
    - `file_id` string, required
    - `name` string, required
    - `bytes` integer, required
    - `files` integer, required
    - `sha256` string, required
  - `messages` object[], required
    - `role` 'user' | 'assistant' | 'tool', required
    - `at` string, date-time
    - `text` string, required

## Response `200`

Updated or unchanged

- object
  - `status` 'updated' | 'unchanged'
  - `trace` LibraryTrace
    - `id` string, required: ltr_…
    - `harness` string, required
    - `session_id` string, required
    - `title` string, nullable
    - `project` string, nullable: The repository's folder name
    - `cwd` string, nullable: Where the session ran, home written as ~
    - `git_branch` string, nullable
    - `git_commit` string, nullable
    - `git_remote` string, nullable: The repository URL, without credentials
    - `model` string, nullable: The model that answered most
    - `models` string[]: Every model that answered, most-used first; empty when the upload named none
    - `harness_version` string, nullable
    - `client` string, nullable: The front end that ran the harness, such as a Claude Code entrypoint or a Codex originator
    - `model_provider` string, nullable
    - `effort` string, nullable
    - `usage` object, nullable: Token totals the source reported, by kind
      - `input_tokens` integer
      - `output_tokens` integer
      - `cache_read_tokens` integer
      - `cache_write_tokens` integer
      - `reasoning_tokens` integer
    - `uploader_id` string, required
    - `device` string, nullable
    - `started_at` string, date-time, nullable
    - `ended_at` string, date-time, nullable
    - `user_turns` integer
    - `tool_calls` integer
    - `messages` integer, required: Stored messages, after redaction
    - `coverage` 'complete' | 'partial' | 'redacted', required
    - `version` integer, required: Raised each time a changed upload replaces it
    - `updated_at` string, date-time, required
    - `environment` object, nullable: The working folder the session ran in, uploaded with it as one of the uploader's files
      - `file_id` string
      - `name` string
      - `bytes` integer
      - `files` integer
      - `sha256` string

## Other responses

- `201`: Created
- `default`: Error — { error: { code, message } }

## Changes

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

[Operation history](https://skmtc.dev/agentsky/apis/agentsky-developer-api/changes/trace-library/:harness/:session_id/put.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/8280a065ef6a?raw)