---
title: dots.v2.agents.sessions.bySession_id().checkpoints.post()
description: CreateCheckpoint captures the session's live sandbox state as a durable checkpoint.
product: Reference
url: https://docs.digitalocean.com/reference/dots/reference/harness-runtime/harness-create-session-checkpoint/
last_updated: "2026-10-27"
---

> **For AI agents:** The documentation index is at [https://docs.digitalocean.com/llms.txt](https://docs.digitalocean.com/llms.txt). Markdown versions of pages use the same URL with `index.html.md` in place of the HTML page (for example, append `index.html.md` to the directory path instead of opening the HTML document).

# dots.v2.agents.sessions.bySession_id().checkpoints.post()

Generated on 27 Oct 2026 from DoTs version [`v1.21.0`](https://github.com/digitalocean/dots/releases/tag/v1.21.0)

## Usage

```typescript
client.v2.agents.sessions.bySession_id(session_id).checkpoints.post(body: Create_checkpoint_request, requestConfiguration?: RequestConfiguration<object>): Promise<undefined | Create_checkpoint_response>
```

## Description

Synchronous: blocks until the capture reaches READY and returns the terminal Checkpoint, clients never see PENDING on this endpoint and need no poll loop. The checkpoint binds the machine-state capture to the event-log cursor at the cut, so it can later seed forks (POST …/fork) and rollback. Checkpoints are taken between turns; a session with an active turn in flight returns 409.

## Parameters

### Path Parameters

`session_id` string required

Example: `a1b2c3d4-e5f6-7890-abcd-ef1234567890`

The session UUID.

### Request Body

`label` string optional

Optional human-readable label stored on the checkpoint; "" if omitted.

## Request Sample

## Show Request Sample

```typescript
import { FetchRequestAdapter } from "@microsoft/kiota-http-fetchlibrary";
import {
    createDigitalOceanClient,
    DigitalOceanApiKeyAuthenticationProvider,
} from "@digitalocean/dots";

const authProvider = new DigitalOceanApiKeyAuthenticationProvider(process.env.DIGITALOCEAN_TOKEN!);
const adapter = new FetchRequestAdapter(authProvider);
const client = createDigitalOceanClient(adapter);

const response = await client.v2.agents.sessions
    .bySession_id("a1b2c3d4-e5f6-7890-abcd-ef1234567890").checkpoints.post({
    label: "string",
});
```

## Response Example

## Show Response Example

```json
{
  "checkpoint": {
    "checkpoint_id": "cp_9f2c1a4b",
    "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "READY",
    "kind": "explicit",
    "label": "before-refactor",
    "event_id": "01JABCDEFGHJKLMNPQRSTVWXYZ",
    "size_bytes": 1048576,
    "created_at": "2026-08-01T12:00:00Z",
    "error_message": "capture timed out"
  }
}
```

## More Information

See [`/v2/agents/sessions/{session_id}/checkpoints`](https://docs.digitalocean.com/reference/api/reference/harness-runtime/index.html.md#harness_create_session_checkpoint) in the API reference for additional detail on responses, headers, parameters, and more.