---
title: "Write a heap snapshot"
method: POST
path: "/api/debug/heap-dump"
tags: ["debug"]
---

# Write a heap snapshot

`POST /api/debug/heap-dump`

## Request

- Base URL: `https://opencode.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://opencode.ai/api/debug/heap-dump`
- Auth: none required

Write a JavaScript heap snapshot of the server process into its log directory, or the requested directory, and return the server-local path once the file is complete. Pauses the server while the heap serializes and can temporarily increase its memory use. The snapshot can contain credentials, prompts, and file contents.

## Query parameters

- `directory` string, nullable: Absolute server-local directory to write the snapshot into, created when missing. Defaults to the server's log directory.

## Response `200`

Success

- object
  - `path` string, required
  - `pid` integer, required
  - `memory` object, required: The server process's memory in bytes, read just before the snapshot (Node's process.memoryUsage()). rss covers native memory the snapshot cannot show.
    - `rss` union, required
      - number
      - 'Infinity' | '-Infinity' | 'NaN'
    - `heapTotal` union, required
      - number
      - 'Infinity' | '-Infinity' | 'NaN'
    - `heapUsed` union, required
      - number
      - 'Infinity' | '-Infinity' | 'NaN'
    - `external` union, required
      - number
      - 'Infinity' | '-Infinity' | 'NaN'
    - `arrayBuffers` union, required
      - number
      - 'Infinity' | '-Infinity' | 'NaN'

## Other responses

- `400`: InvalidRequestError
- `401`: UnauthorizedError
- `500`: UnknownError

## Changes

> 50 revisions in range; 1 not diffed.

- **2026-10-23** `499220956e7f`: 1 info
  - added the required property `memory` to the response with the `200` status
- **2026-10-23** `f52efc43928f`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/kaaass/apis/opencode/changes/api/debug/heap-dump/post.md)

---

[API](https://skmtc.dev/kaaass/apis/opencode.md) - [All operations](https://skmtc.dev/kaaass/apis/opencode/llms.txt) - [OpenAPI document](https://skmtc.dev/kaaass/apis/opencode/revisions/4e083d954707?raw)