# `GET /v1/sessions/{sessionId}/export` — Export a session

Part of the [Bkper Managed Agent API](https://bkper.com/docs/api/managed-agent.md). Read its guide for authentication, conventions, and examples.

The whole session as one JSON attachment (SessionExport), for its owner and for those it is shared with. Reads only what is recorded; never starts the sandbox. Not a format to resume the session from.

## Operation contract

```json
{
  "operationId": "exportSession",
  "tags": [
    "Sessions"
  ],
  "summary": "Export a session",
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "sessionId",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      }
    }
  ],
  "description": "The whole session as one JSON attachment (SessionExport), for its owner and for those it is shared with. Reads only what is recorded; never starts the sandbox. Not a format to resume the session from.",
  "responses": {
    "200": {
      "description": "Success",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SessionExport"
          }
        }
      }
    },
    "400": {
      "description": "Rejected; never contains credentials or upstream payloads.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "Rejected; never contains credentials or upstream payloads.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Rejected; never contains credentials or upstream payloads.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "Rejected; never contains credentials or upstream payloads.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "409": {
      "description": "Rejected; never contains credentials or upstream payloads.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "410": {
      "description": "Rejected; never contains credentials or upstream payloads.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "411": {
      "description": "Rejected; never contains credentials or upstream payloads.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "413": {
      "description": "Rejected; never contains credentials or upstream payloads.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "503": {
      "description": "Rejected; never contains credentials or upstream payloads.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}
```

## Schemas

### SessionExport

```json
{
  "type": "object",
  "properties": {
    "format": {
      "type": "string",
      "const": "bkper.agent.session-export"
    },
    "contractVersion": {
      "type": "string",
      "description": "The version of this contract the objects follow."
    },
    "exportedAt": {
      "type": "string",
      "pattern": "^\\d+$",
      "description": "Milliseconds since the epoch, as a string."
    },
    "session": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "title": {
          "type": "string"
        },
        "createdAt": {
          "type": "string",
          "pattern": "^\\d+$",
          "description": "Milliseconds since the epoch, as a string."
        },
        "updatedAt": {
          "type": "string",
          "pattern": "^\\d+$",
          "description": "Milliseconds since the epoch, as a string."
        },
        "status": {
          "type": "string",
          "description": "Run state. Open: idle | working | stopping."
        },
        "archived": {
          "type": "boolean"
        },
        "parent": {
          "type": "object",
          "properties": {
            "sessionId": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            },
            "entryId": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            },
            "kind": {
              "type": "string",
              "const": "fork"
            },
            "position": {
              "type": "string",
              "description": "Fork boundary: at inherits history through entryId; before inherits history before it. Open: at | before."
            }
          },
          "required": [
            "sessionId",
            "entryId",
            "kind",
            "position"
          ]
        },
        "model": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "thinkingLevel": {
              "description": "Sent to Bkper AI as it is. Without one, its default for the model applies.",
              "type": "string"
            }
          },
          "required": [
            "id"
          ]
        },
        "context": {
          "type": "object",
          "properties": {
            "tokens": {
              "type": "number"
            },
            "window": {
              "type": "number"
            }
          },
          "required": [
            "tokens",
            "window"
          ],
          "description": "Current conversation."
        },
        "usage": {
          "type": "object",
          "properties": {
            "inputTokens": {
              "type": "number"
            },
            "outputTokens": {
              "type": "number"
            },
            "cacheReadTokens": {
              "type": "number"
            },
            "cacheWriteTokens": {
              "type": "number"
            },
            "estimatedCost": {
              "type": "string",
              "description": "USD estimate from catalog prices; Bkper AI accounting is authoritative."
            }
          },
          "required": [
            "inputTokens",
            "outputTokens",
            "cacheReadTokens",
            "cacheWriteTokens",
            "estimatedCost"
          ],
          "description": "This conversation only; inherited history is not counted again."
        },
        "properties": {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "type": "string"
          }
        },
        "instructions": {
          "description": "Present when set. Without it the agent runs with Bkper's base only.",
          "type": "string",
          "maxLength": 16000
        },
        "shared": {
          "type": "boolean",
          "description": "Whether the owner shares this session with its audience, read-only."
        },
        "bookId": {
          "description": "The Book the session was started in: its first input's bookContext. Fixed once set; absent when that input had none.",
          "type": "string"
        },
        "owner": {
          "description": "Present when the session is someone else's, shared with the caller: the caller can read and continue it, never change it.",
          "type": "object",
          "properties": {
            "name": {
              "description": "The owner's display name, as Bkper verified it.",
              "type": "string"
            }
          }
        },
        "continuedFrom": {
          "description": "Present when the session was copied from another person's shared session, to continue it as the caller's own. The original is unchanged; the copy carries its history, not its files or instructions. Such a session has no parent.",
          "type": "object",
          "properties": {
            "sessionId": {
              "type": "string"
            },
            "entryId": {
              "type": "string"
            },
            "position": {
              "type": "string",
              "description": "Where the copy ends: through entryId, or before it. Open: at | before."
            },
            "owner": {
              "type": "object",
              "properties": {
                "name": {
                  "description": "The original's owner, as Bkper verified them when copied.",
                  "type": "string"
                }
              }
            }
          },
          "required": [
            "sessionId",
            "entryId",
            "position",
            "owner"
          ]
        }
      },
      "required": [
        "id",
        "createdAt",
        "updatedAt",
        "status",
        "archived",
        "model",
        "context",
        "usage",
        "properties",
        "shared"
      ]
    },
    "entries": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "createdAt": {
            "type": "string",
            "pattern": "^\\d+$",
            "description": "Milliseconds since the epoch, as a string."
          },
          "type": {
            "type": "string",
            "description": "Entry type. Open: user | assistant | tool_result | compaction."
          },
          "createdBy": {
            "type": "string"
          },
          "inputId": {
            "type": "string"
          },
          "delivery": {
            "type": "string"
          },
          "bookContext": {
            "type": "object",
            "properties": {
              "bookId": {
                "type": "string",
                "pattern": "^[A-Za-z0-9_-]{1,128}$"
              },
              "query": {
                "type": "string",
                "maxLength": 4000,
                "pattern": "^[^\\u0000-\\u001f]*$"
              }
            },
            "required": [
              "bookId",
              "query"
            ],
            "additionalProperties": false
          },
          "attributes": {
            "type": "object",
            "propertyNames": {
              "type": "string",
              "pattern": "^[A-Za-z][A-Za-z0-9_.-]{0,63}$"
            },
            "additionalProperties": {
              "type": "string",
              "maxLength": 16000
            },
            "description": "Up to 16 string attributes of the message, such as its sender, channel or thread, at most 16000 characters in total. Names start with a letter, then up to 63 letters, digits, `_`, `.` or `-`. Advisory data for the agent, frozen with the input: never identity, permission or instructions."
          },
          "content": {
            "description": "user: text and attached file parts; assistant: text, thinking and tool_call blocks; tool_result: text parts, and a file part from publish. A tool_call has callId, name and arguments as the agent sent them, and a summary when the agent named the step in a few plain words for people.",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string"
                }
              },
              "required": [
                "type"
              ],
              "additionalProperties": {},
              "description": "Typed part; text is { type: \"text\", text }. Open."
            }
          },
          "model": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "description": "Assistant outcome. Open: completed | incomplete."
          },
          "incompleteReason": {
            "type": "string",
            "description": "Why incomplete. Open: cancelled | inference_failed | interrupted."
          },
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "type": {
                "type": "string"
              }
            },
            "required": [
              "code"
            ],
            "description": "Sanitized failure. Never contains provider, AI or credential text."
          },
          "durationMs": {
            "description": "assistant: milliseconds from createdAt until the response ended; tool_result: milliseconds the tool ran. Absent when not measured.",
            "type": "number"
          },
          "callId": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "isError": {
            "type": "boolean"
          },
          "details": {},
          "diagnostics": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "severity": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              },
              "required": [
                "severity",
                "message"
              ]
            }
          },
          "reason": {
            "type": "string",
            "description": "Compaction trigger. Open: manual | threshold | overflow."
          },
          "summary": {
            "type": "string"
          },
          "clipped": {
            "description": "Large strings were shortened; GET the entry for its full content.",
            "type": "boolean"
          }
        },
        "required": [
          "id",
          "createdAt",
          "type"
        ],
        "description": "Immutable transcript entry. Clients ignore unknown fields and render unknown types generically."
      },
      "description": "Every entry in full, never clipped, oldest first: history inherited from a fork or copied from a shared session included."
    },
    "files": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "origin": {
            "type": "string",
            "description": "Uploaded by the user, or published by the agent. Open: upload | publish."
          },
          "sessionId": {
            "description": "The session that published it. Absent on uploads, which belong to the user.",
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "mediaType": {
            "type": "string",
            "description": "Published: the allowlisted type for its name. Uploaded: as declared by the uploader, unverified. Downloads always use the allowlisted type for the name; anything else is application/octet-stream."
          },
          "size": {
            "type": "number",
            "description": "Bytes."
          },
          "sha256": {
            "type": "string",
            "description": "Hex SHA-256 of the content."
          },
          "createdAt": {
            "type": "string",
            "pattern": "^\\d+$",
            "description": "Milliseconds since the epoch, as a string."
          },
          "createdBy": {
            "type": "string"
          },
          "expiresAt": {
            "type": "string",
            "pattern": "^\\d+$",
            "description": "When the stored copy is deleted, 30 days after creation. Then downloads are 410 file_gone."
          }
        },
        "required": [
          "id",
          "origin",
          "name",
          "mediaType",
          "size",
          "sha256",
          "createdAt",
          "createdBy",
          "expiresAt"
        ],
        "description": "An immutable private copy of a file, kept for 30 days. Only its owner can read or download it, and, through the session routes, those a session that holds it is shared with."
      },
      "description": "The files the session holds, without their contents, oldest first: attached to its own inputs or published by it, and those its history shows, inherited fork history included. Files of messages copied from another person's session stay theirs: only the entries' file parts name them."
    },
    "inputs": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The Idempotency-Key."
          },
          "createdAt": {
            "type": "string",
            "pattern": "^\\d+$",
            "description": "Milliseconds since the epoch, as a string."
          },
          "versions": {
            "type": "object",
            "properties": {
              "agent": {
                "description": "The Agent's deployed version.",
                "type": "string"
              },
              "cli": {
                "description": "The `bkper` CLI version in the sandbox.",
                "type": "string"
              }
            },
            "description": "What ran it, when recorded: absent for inputs from before versions were recorded."
          }
        },
        "required": [
          "id",
          "createdAt",
          "versions"
        ]
      },
      "description": "The session's own inputs, oldest first."
    }
  },
  "required": [
    "format",
    "contractVersion",
    "exportedAt",
    "session",
    "entries",
    "files",
    "inputs"
  ],
  "description": "A session in one file, for support or another agent to read. Not a format to resume the session from."
}
```

### Error

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "Stable code, e.g. not_found, idempotency_conflict, session_working, usage_limit_exceeded. Open."
        },
        "type": {
          "description": "Category, e.g. invalid_request_error, authentication_error, usage_limit_error. Open.",
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "host": {
          "description": "host_in_use: the host another service holds.",
          "type": "string"
        },
        "service": {
          "description": "host_in_use: the id of the service that holds the host.",
          "type": "string"
        }
      },
      "required": [
        "code"
      ]
    }
  },
  "required": [
    "error"
  ]
}
```

## Authentication

```json
{
  "bearerAuth": {
    "type": "http",
    "scheme": "bearer"
  }
}
```