API

Save an owned Chat session in a workspace

Generated from the checked-in source. Do not edit this reference by hand.

PUT /api/v1/workspaces/{workspace}/chats/{id}

Requires workspace write access. Stores conversation content separately from accounting. Only supported top-level and nested fields are retained. Client-supplied accounting fields are discarded. Numeric timestamps, durations and token counts must be nonnegative JavaScript-safe integers; token counts may be null. Settings and attachment shapes are validated. This endpoint does not establish authoritative request charges or detect secrets embedded in conversation text. Omit expectedRevision for a compatibility write only while the owned record has not enabled guarded writes. Explicit null creates only if no owned row exists; a canonical positive decimal revision updates only that exact owned version. Stale, missing or duplicate-create guarded writes return 409 without replacing content. Revisions are global sequence values, not timestamps, and are never reused by API delete/recreate. Guarded success includes a decimal revision; direct GET provides it. A successful guarded creation/update permanently enables guarded writes on that owned row. Compatibility saves thereafter return 409; there is no content-write downgrade. A content-free guard identity survives deletion, so legacy autosaves cannot resurrect a protected reference; explicit null guarded creation may recreate it. Untouched legacy rows retain compatibility behavior until guarded save. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.

Operation: saveChatSessionByWorkspace.

Authentication

Use the credential and permission scope described above. Each object below is an alternative; schemes within one object are required together.

[
  {
    "bearerAuth": []
  }
]

HTTP request

Set NIU_ORIGIN to your installation origin (without /v1). Replace path, query and header placeholders with the required values. Query examples use curl 7.87 or newer to encode values with --url-query. Use the credential scope described above; a bearer token must have the authority required by this operation.

curl --fail-with-body -X PUT "$NIU_ORIGIN/api/v1/workspaces/{workspace}/chats/{id}" \
  -H "Authorization: Bearer $NIU_BEARER_TOKEN" \
  -H 'Content-Type: application/json' \
  --data @request.json

Parameters

workspace

Location: path. Required.

{
  "type": "string",
  "format": "uuid"
}

id

Location: path. Required.

{
  "type": "string",
  "format": "uuid"
}

Request body

application/json

Required.

{
  "type": "object",
  "required": [
    "prompt",
    "results",
    "createdAt"
  ],
  "properties": {
    "prompt": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "createdAt": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "turns": {
      "type": "array",
      "maxItems": 100,
      "description": "Ordered conversation turns. Each retains its prompt and up to four model responses, validated with the same result fields as the current turn. Unknown turn/result fields are stripped. Optional for legacy single-turn sessions.",
      "items": {
        "type": "object",
        "required": [
          "prompt",
          "results"
        ],
        "properties": {
          "prompt": {
            "type": "string"
          },
          "results": {
            "type": "array",
            "maxItems": 4,
            "items": {
              "type": "object"
            }
          },
          "attachments": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "name",
                "type",
                "content"
              ],
              "properties": {
                "name": {
                  "type": "string"
                },
                "type": {
                  "type": "string"
                },
                "content": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "results": {
      "type": "array",
      "maxItems": 4,
      "items": {
        "type": "object",
        "required": [
          "model",
          "content",
          "elapsedMs",
          "phase"
        ],
        "properties": {
          "model": {
            "type": "string"
          },
          "content": {
            "type": "string"
          },
          "elapsedMs": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "finishReason": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 128,
            "description": "Model completion reason, when supplied. Transport completion alone does not establish a complete answer."
          },
          "phase": {
            "type": "string",
            "enum": [
              "connecting",
              "streaming",
              "complete",
              "failed",
              "cancelled"
            ]
          },
          "promptTokens": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "completionTokens": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "totalTokens": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0,
            "maximum": 9007199254740991
          }
        }
      }
    },
    "settings": {
      "type": "object",
      "properties": {
        "systemPrompt": {
          "type": "string"
        },
        "maxTokens": {
          "type": "integer",
          "minimum": 1
        },
        "temperature": {
          "type": "number",
          "minimum": 0,
          "maximum": 2
        },
        "logPayloads": {
          "type": "boolean"
        }
      }
    },
    "attachments": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "name",
          "type",
          "content"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "content": {
            "type": "string"
          }
        }
      }
    },
    "expectedRevision": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[1-9][0-9]*$",
      "description": "Omitted: compatibility write. Null: create-only. Positive decimal string: exact current revision from GET."
    }
  }
}

Responses

HTTP 200

Compatibility saved flag, or confirmed guarded saved flag, revision and guardedWrites=true.

Content type: application/json.

{
  "type": "object",
  "required": [
    "saved"
  ],
  "properties": {
    "saved": {
      "const": true
    },
    "reference": {
      "type": [
        "string",
        "null"
      ],
      "description": "Permanent server-assigned Chat reference for product links."
    },
    "revision": {
      "type": "string",
      "pattern": "^[1-9][0-9]*$"
    },
    "guardedWrites": {
      "const": true,
      "description": "Present with revision only for confirmed guarded saves; older compatibility servers do not confirm this mode."
    }
  }
}

HTTP 400

Invalid content or expected revision.

HTTP 401

Authentication required.

HTTP 403

Workspace write access required.

HTTP 404

Resource missing or outside authorized workspace/owner scope.

HTTP 409

Guarded creation/update does not match current owned state.

HTTP 413

Request exceeds the 24 MiB transport limit.

HTTP 503

Storage unavailable or bounded write wait exceeded.

Behavior and supported scope

Supported scope: implemented