---
title: "The fleet · intentic sandbox API"
description: "Every registered conversation, its accumulated diff, and landing or discarding its work. Every route in the the fleet group of the intentic sandbox API, with its input, its answer and a playground."
url: "https://intentic.dev/api/agents/"
---

Agents

# The fleet

Every registered conversation, its accumulated diff, and landing or discarding its work

**On this page (19 sections)**

- [Every live conversation](#agents-list)
- [Conversations put away](#agents-archived)
- [Find a conversation](#agents-search)
- [One conversation's card](#agents-get)
- [The full conversation record](#agents-transcript)
- [Put words in the agent's mouth](#agents-place)
- [Retitle a conversation](#agents-rename)
- [Whether this conversation merges its work automatically](#agents-autoLand)
- [Whether this conversation retries after a provider outage](#agents-resumeAfterOutage)
- [Mark a conversation read](#agents-seen)
- [Mark every conversation read](#agents-seenAll)
- [Everything a conversation has changed](#agents-diff)
- [One file's before and after in a conversation's work](#agents-fileDiff)
- [Merge a conversation's work into the workspace](#agents-land)
- [Ask a maintainer to merge this work](#agents-requestLand)
- [Throw a conversation's work away](#agents-discard)
- [Put conversations away](#agents-archive)
- [Bring conversations back](#agents-unarchive)
- [Empty the archive for good](#agents-purge)

The roster rather than the turn. Each conversation works in its own private copy of the repos, so it has a cumulative set of changes you can read and two ways for it to end: merge that work into the shared tree, or throw it away. The rest is the bookkeeping a board needs — renaming, marking read, archiving, purging.

19 calls. Pick one to open it, or use the list on the right.

**GET`/agents` Every live conversation**

The fleet as the board draws it: each conversation with its title, what it is doing, when it last moved and whether anybody has read it since. Archived conversations are not in here.

### What you send

Nothing. Call it as it is.

### What comes back

| Field | Type |
| --- | --- |
| `agents` The conversations | object[] |
| `id` The conversation id, which is how… | string |
| `sessionId` The provider session behind the last… | string |
| `title` What to call it: the first… | string |
| `status` What it is doing | "idle" | "running" | "awaiting" | "stopping" … (11) |
| `failure` Why the last turn failed, in… | string |
| `provider` Which model provider it runs on | string |
| `harness` Which agentic loop it runs on | "native" | "claude-code" |
| `model` What its last turn ran with | string |
| `effort` How hard that turn was told… | string |
| `thinking` Whether that turn showed its reasoning | boolean |
| `fast` Whether that turn asked for higher… | boolean |
| `tier` How hard its last turn looked… | "fast" | "standard" |
| `tierHold` Whether this conversation is pinned to… | boolean |
| `account` Which connected account paid for it | string |
| `branch` The branch its private copy works… | string |
| `autoLand` This conversation's own answer to whether… | boolean |
| `resumeAfterOutage` | boolean |
| `landRequested` A collaborator has asked a maintainer… | object |
| `email` Who asked | string |
| `name` Their display name | string |
| `at` When they asked, in milliseconds | number |
| `origin` Where the conversation came from when… | object |
| `automationId` | string |
| `provider` | string |
| `channelId` | string |
| `author` | string |
| `forkedFrom` The conversation this one was cut… | object |
| `conversationId` | string |
| `index` | integer |
| `files` | "then" | "now" |
| `base` The commit its private copy started… | string |
| `costUsd` What it has cost so far,… | number |
| `inputTokens` Tokens sent | number |
| `outputTokens` Tokens received | number |
| `contextTokens` How much of the window the… | number |
| `contextWindow` How large that window is | number |
| `activity` What it is doing at this… | object |
| `tool` The last tool it reached for | string |
| `target` What it reached for that tool… | string |
| `todo` The item on its own list… | string |
| `landedMessageDraft` The whole story of this merge's… | object |
| `startedAt` When the drafting began, in milliseconds | number |
| `steps` Each model that was asked, in… | object[] |
| `provider` Which provider was asked | string |
| `model` Which of its models | string |
| `status` How this one went | "asking" | "answered" | "refused" | "skipped" |
| `at` When it started being asked, in… | number |
| `ms` How long it took | number |
| `reason` Why it refused, in its own… | string |
| `outcome` How it ended | "written" | "failed" |
| `reason` The one-line account of a failure,… | string |
| `finishedAt` When it ended, in milliseconds | number |
| `landedMessage` What this conversation's merged work is… | object |
| `subject` One line saying what the merged… | string |
| `note` The same change said to somebody… | string |
| `breaking` What this change takes away, for… | string |
| `startedAt` When the running turn started, in… | number |
| `updatedAt` When it last did something, in… | number |
| `seenAt` When somebody last opened it, in… | number |
| `attention` Which kinds of waiting-for-you it is… | object |
| `plan` It has proposed a plan and… | boolean |
| `question` It has asked you something | boolean |
| `permission` It wants to use a tool… | boolean |
| `service` It wants to spend money on… | boolean |
| `capability` It needs something connected that is… | boolean |
| `conflict` Its work cannot be merged without… | boolean |
| `turns` Turns it has finished | number |
| `toolUses` Tools it has used, over its… | number |
| `subagents` Helper agents this one delegated to | object |
| `running` Helpers working right now | number |
| `total` Helpers it has started over its… | number |
| `diff` Everything it has written, measured from… | object |
| `files` Files touched | number |
| `insertions` Lines added | number |
| `deletions` Lines removed | number |
| `landedPresence` Present only when some of what… | object |
| `landed` Paths this conversation merged in | number |
| `present` How many of them are still… | number |
| `loop` The loop driving this conversation, if… | object |
| `state` How the loop is going | "running" | "done" | "exhausted" | "stalled" … (7) |
| `iteration` Which round it is on | integer |
| `maxIterations` How many rounds it will attempt… | integer |
| `goal` What it is looping towards | string |
| `workflow` The workflow run this conversation is… | object |
| `runId` The run this belongs to, which… | string |
| `name` The workflow's name | string |
| `step` Which step this conversation is on… | string |
| `index` This step's place in the workflow,… | integer |
| `total` How many steps the workflow has | integer |
| `archivedAt` When it was put away, in… | number |
| `rev` Which version of the fleet this… | number |
| `held` Automations waiting at the door for… | object[] |
| `id` This waiting item's own id, which… | string |
| `automationId` Which automation it came from | string |
| `payload` What set it off, kept whole… | string |
| `origin` Where the message came from, kept… | object |
| `automationId` | string |
| `provider` | string |
| `channelId` | string |
| `author` | string |
| `title` What the conversation would be called | string |
| `conversationId` The thread this belongs to, when… | string |
| `sessionId` The provider session that thread last… | string |
| `createdAt` When it started waiting, in milliseconds | number |
| `autoRunAt` When it goes ahead on its… | number |

Try it answered in this tab

curl

```bash
curl "$SANDBOX/agents" \
 -H "x-intentic-control: $INTENTIC_TOKEN"
```

TypeScript

```typescript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.agents.list();
```

**GET`/agents/archived` Conversations put away**

The same shape as the live fleet, for the conversations somebody has decided are finished. Their work is kept, and any one of them can be brought back.

### What you send

Nothing. Call it as it is.

### What comes back

| Field | Type |
| --- | --- |
| `agents` The conversations | object[] |
| `id` The conversation id, which is how… | string |
| `sessionId` The provider session behind the last… | string |
| `title` What to call it: the first… | string |
| `status` What it is doing | "idle" | "running" | "awaiting" | "stopping" … (11) |
| `failure` Why the last turn failed, in… | string |
| `provider` Which model provider it runs on | string |
| `harness` Which agentic loop it runs on | "native" | "claude-code" |
| `model` What its last turn ran with | string |
| `effort` How hard that turn was told… | string |
| `thinking` Whether that turn showed its reasoning | boolean |
| `fast` Whether that turn asked for higher… | boolean |
| `tier` How hard its last turn looked… | "fast" | "standard" |
| `tierHold` Whether this conversation is pinned to… | boolean |
| `account` Which connected account paid for it | string |
| `branch` The branch its private copy works… | string |
| `autoLand` This conversation's own answer to whether… | boolean |
| `resumeAfterOutage` | boolean |
| `landRequested` A collaborator has asked a maintainer… | object |
| `email` Who asked | string |
| `name` Their display name | string |
| `at` When they asked, in milliseconds | number |
| `origin` Where the conversation came from when… | object |
| `automationId` | string |
| `provider` | string |
| `channelId` | string |
| `author` | string |
| `forkedFrom` The conversation this one was cut… | object |
| `conversationId` | string |
| `index` | integer |
| `files` | "then" | "now" |
| `base` The commit its private copy started… | string |
| `costUsd` What it has cost so far,… | number |
| `inputTokens` Tokens sent | number |
| `outputTokens` Tokens received | number |
| `contextTokens` How much of the window the… | number |
| `contextWindow` How large that window is | number |
| `activity` What it is doing at this… | object |
| `tool` The last tool it reached for | string |
| `target` What it reached for that tool… | string |
| `todo` The item on its own list… | string |
| `landedMessageDraft` The whole story of this merge's… | object |
| `startedAt` When the drafting began, in milliseconds | number |
| `steps` Each model that was asked, in… | object[] |
| `provider` Which provider was asked | string |
| `model` Which of its models | string |
| `status` How this one went | "asking" | "answered" | "refused" | "skipped" |
| `at` When it started being asked, in… | number |
| `ms` How long it took | number |
| `reason` Why it refused, in its own… | string |
| `outcome` How it ended | "written" | "failed" |
| `reason` The one-line account of a failure,… | string |
| `finishedAt` When it ended, in milliseconds | number |
| `landedMessage` What this conversation's merged work is… | object |
| `subject` One line saying what the merged… | string |
| `note` The same change said to somebody… | string |
| `breaking` What this change takes away, for… | string |
| `startedAt` When the running turn started, in… | number |
| `updatedAt` When it last did something, in… | number |
| `seenAt` When somebody last opened it, in… | number |
| `attention` Which kinds of waiting-for-you it is… | object |
| `plan` It has proposed a plan and… | boolean |
| `question` It has asked you something | boolean |
| `permission` It wants to use a tool… | boolean |
| `service` It wants to spend money on… | boolean |
| `capability` It needs something connected that is… | boolean |
| `conflict` Its work cannot be merged without… | boolean |
| `turns` Turns it has finished | number |
| `toolUses` Tools it has used, over its… | number |
| `subagents` Helper agents this one delegated to | object |
| `running` Helpers working right now | number |
| `total` Helpers it has started over its… | number |
| `diff` Everything it has written, measured from… | object |
| `files` Files touched | number |
| `insertions` Lines added | number |
| `deletions` Lines removed | number |
| `landedPresence` Present only when some of what… | object |
| `landed` Paths this conversation merged in | number |
| `present` How many of them are still… | number |
| `loop` The loop driving this conversation, if… | object |
| `state` How the loop is going | "running" | "done" | "exhausted" | "stalled" … (7) |
| `iteration` Which round it is on | integer |
| `maxIterations` How many rounds it will attempt… | integer |
| `goal` What it is looping towards | string |
| `workflow` The workflow run this conversation is… | object |
| `runId` The run this belongs to, which… | string |
| `name` The workflow's name | string |
| `step` Which step this conversation is on… | string |
| `index` This step's place in the workflow,… | integer |
| `total` How many steps the workflow has | integer |
| `archivedAt` When it was put away, in… | number |
| `rev` Which version of the fleet this… | number |
| `held` Automations waiting at the door for… | object[] |
| `id` This waiting item's own id, which… | string |
| `automationId` Which automation it came from | string |
| `payload` What set it off, kept whole… | string |
| `origin` Where the message came from, kept… | object |
| `automationId` | string |
| `provider` | string |
| `channelId` | string |
| `author` | string |
| `title` What the conversation would be called | string |
| `conversationId` The thread this belongs to, when… | string |
| `sessionId` The provider session that thread last… | string |
| `createdAt` When it started waiting, in milliseconds | number |
| `autoRunAt` When it goes ahead on its… | number |

Try it answered in this tab

curl

```bash
curl "$SANDBOX/agents/archived" \
 -H "x-intentic-control: $INTENTIC_TOKEN"
```

TypeScript

```typescript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.agents.archived();
```

**GET`/agents/search` Find a conversation**

Searches the live fleet and the archive together. Both halves on purpose: the board hides finished work by design, and a filter that says it found nothing while the answer sits one click away is simply wrong.

### What you send

| Field | Type | Where |
| --- | --- | --- |
| `query` required What to look for | string | query |
| `caseSensitive` Whether capitals matter | string | query |

### What comes back

| Field | Type |
| --- | --- |
| `matches` What matched, from the live fleet… | object[] |
| `id` Which conversation matched | string |
| `snippet` Why, in its own words | object |
| `text` The matching line, with a little… | string |
| `speaker` Who said it | "user" | "agent" |
| `scanned` How many conversations were actually read,… | number |
| `indexing` Whether what was said is still… | boolean |

Try it answered in this tab

curl

```bash
curl "$SANDBOX/agents/search?query=%E2%80%A6" \
 -H "x-intentic-control: $INTENTIC_TOKEN"
```

TypeScript

```typescript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.agents.search({
 "query": "…"
});
```

**GET`/agents/{id}` One conversation's card**

Everything the board shows for a single conversation: its title, state, working branch, unread marker and timestamps.

### What you send

| Field | Type | Where |
| --- | --- | --- |
| `id` required Which conversation | string | address |

### What comes back

| Field | Type |
| --- | --- |
| `id` The conversation id, which is how… | string |
| `sessionId` The provider session behind the last… | string |
| `title` What to call it: the first… | string |
| `status` What it is doing | "idle" | "running" | "awaiting" | "stopping" … (11) |
| `failure` Why the last turn failed, in… | string |
| `provider` Which model provider it runs on | string |
| `harness` Which agentic loop it runs on | "native" | "claude-code" |
| `model` What its last turn ran with | string |
| `effort` How hard that turn was told… | string |
| `thinking` Whether that turn showed its reasoning | boolean |
| `fast` Whether that turn asked for higher… | boolean |
| `tier` How hard its last turn looked… | "fast" | "standard" |
| `tierHold` Whether this conversation is pinned to… | boolean |
| `account` Which connected account paid for it | string |
| `branch` The branch its private copy works… | string |
| `autoLand` This conversation's own answer to whether… | boolean |
| `resumeAfterOutage` | boolean |
| `landRequested` A collaborator has asked a maintainer… | object |
| `email` Who asked | string |
| `name` Their display name | string |
| `at` When they asked, in milliseconds | number |
| `origin` Where the conversation came from when… | object |
| `automationId` | string |
| `provider` | string |
| `channelId` | string |
| `author` | string |
| `forkedFrom` The conversation this one was cut… | object |
| `conversationId` | string |
| `index` | integer |
| `files` | "then" | "now" |
| `base` The commit its private copy started… | string |
| `costUsd` What it has cost so far,… | number |
| `inputTokens` Tokens sent | number |
| `outputTokens` Tokens received | number |
| `contextTokens` How much of the window the… | number |
| `contextWindow` How large that window is | number |
| `activity` What it is doing at this… | object |
| `tool` The last tool it reached for | string |
| `target` What it reached for that tool… | string |
| `todo` The item on its own list… | string |
| `landedMessageDraft` The whole story of this merge's… | object |
| `startedAt` When the drafting began, in milliseconds | number |
| `steps` Each model that was asked, in… | object[] |
| `provider` Which provider was asked | string |
| `model` Which of its models | string |
| `status` How this one went | "asking" | "answered" | "refused" | "skipped" |
| `at` When it started being asked, in… | number |
| `ms` How long it took | number |
| `reason` Why it refused, in its own… | string |
| `outcome` How it ended | "written" | "failed" |
| `reason` The one-line account of a failure,… | string |
| `finishedAt` When it ended, in milliseconds | number |
| `landedMessage` What this conversation's merged work is… | object |
| `subject` One line saying what the merged… | string |
| `note` The same change said to somebody… | string |
| `breaking` What this change takes away, for… | string |
| `startedAt` When the running turn started, in… | number |
| `updatedAt` When it last did something, in… | number |
| `seenAt` When somebody last opened it, in… | number |
| `attention` Which kinds of waiting-for-you it is… | object |
| `plan` It has proposed a plan and… | boolean |
| `question` It has asked you something | boolean |
| `permission` It wants to use a tool… | boolean |
| `service` It wants to spend money on… | boolean |
| `capability` It needs something connected that is… | boolean |
| `conflict` Its work cannot be merged without… | boolean |
| `turns` Turns it has finished | number |
| `toolUses` Tools it has used, over its… | number |
| `subagents` Helper agents this one delegated to | object |
| `running` Helpers working right now | number |
| `total` Helpers it has started over its… | number |
| `diff` Everything it has written, measured from… | object |
| `files` Files touched | number |
| `insertions` Lines added | number |
| `deletions` Lines removed | number |
| `landedPresence` Present only when some of what… | object |
| `landed` Paths this conversation merged in | number |
| `present` How many of them are still… | number |
| `loop` The loop driving this conversation, if… | object |
| `state` How the loop is going | "running" | "done" | "exhausted" | "stalled" … (7) |
| `iteration` Which round it is on | integer |
| `maxIterations` How many rounds it will attempt… | integer |
| `goal` What it is looping towards | string |
| `workflow` The workflow run this conversation is… | object |
| `runId` The run this belongs to, which… | string |
| `name` The workflow's name | string |
| `step` Which step this conversation is on… | string |
| `index` This step's place in the workflow,… | integer |
| `total` How many steps the workflow has | integer |
| `archivedAt` When it was put away, in… | number |

Try it answered in this tab

curl

```bash
curl "$SANDBOX/agents/a1b2c3d4" \
 -H "x-intentic-control: $INTENTIC_TOKEN"
```

TypeScript

```typescript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.agents.get({
 "id": "a1b2c3d4"
});
```

**GET`/agents/{id}/transcript` The full conversation record**

Every message in one conversation, in order, including the tool calls and their results. This is the record the chat replays and the next turn is seeded from.

### What you send

| Field | Type | Where |
| --- | --- | --- |
| `id` required Which conversation | string | address |

### What comes back

| Field | Type |
| --- | --- |
| `messages` The conversation, in order | object[] |
| `role` Who said it | "user" | "assistant" | "notice" |
| `text` The words | string |
| `sentAt` When it was sent, in milliseconds | number |
| `attachments` Files attached to this message, as… | string[] |
| `checkpointId` The saved point this message can… | string |
| `thinking` What the agent was reasoning about | string |
| `tools` The tool calls this part of… | object[] |
| `id` The call's id | string |
| `name` Which tool | string |
| `category` What kind of thing it does:… | "read" | "edit" | "delete" | "move" … (9) |
| `status` How it went | "pending" | "in_progress" | "completed" | "failed" |
| `target` What it acted on, in one… | string |
| `locations` The files it touched | object[] |
| `path` The file, as a workspace path,… | string |
| `line` Which line, counting from one | number |
| `content` What it produced: text, a change… | object[] |
| `type` Plain output | "text" |
| `text` What the tool said | string |
| `children` Calls a delegated helper made, nested… | object[] |
| `id` The call's id | string |
| `name` Which tool | string |
| `category` What kind of thing it does:… | "read" | "edit" | "delete" | "move" … (9) |
| `status` How it went | "pending" | "in_progress" | "completed" | "failed" |
| `target` What it acted on, in one… | string |
| `locations` The files it touched | object[] |
| `content` What it produced: text, a change… | object[] |
| `children` Calls a delegated helper made, nested… | object[] |
| `thinking` What the agent was reasoning about… | string |
| `thinking` What the agent was reasoning about… | string |
| `notes` What the sandbox added to this… | object[] |
| `title` The one line a reader sees,… | string |
| `text` The note itself, which is also… | string |
| `placed` A person wrote this in the… | boolean |
| `noticeAction` A one-press follow-up this recorded notice… | "tierHold" |
| `sessionId` The provider session behind the last… | string |

Try it answered in this tab

curl

```bash
curl "$SANDBOX/agents/a1b2c3d4/transcript" \
 -H "x-intentic-control: $INTENTIC_TOKEN"
```

TypeScript

```typescript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.agents.transcript({
 "id": "a1b2c3d4"
});
```

**POST`/agents/{id}/place` Put words in the agent's mouth**

Writes a line into the record as though the agent had said it, with no turn behind it and no reply. Human readers see it marked as placed. The next real turn starts fresh from the record, where the line reads as the agent's own. Refused while a turn is running.

### What you send

| Field | Type | Where |
| --- | --- | --- |
| `id` required Which conversation | string | address |
| `text` required The words to put in the… | string | body |

### What comes back

| Field | Type |
| --- | --- |
| `ok` Always true | true |

Try it answered in this tab

curl

```bash
curl -X POST "$SANDBOX/agents/a1b2c3d4/place" \
 -H "x-intentic-control: $INTENTIC_TOKEN" \
 -H "content-type: application/json" \
 -d '{"text":"export const start = () => listen(PORT);\n"}'
```

TypeScript

```typescript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.agents.place({
 "id": "a1b2c3d4",
 "text": "export const start = () => listen(PORT);\n"
});
```

**POST`/agents/{id}/rename` Retitle a conversation**

Sets the title a person chose, replacing the one that was generated. Allowed while the conversation is working, and it does not count as activity.

### What you send

| Field | Type | Where |
| --- | --- | --- |
| `id` required Which conversation | string | address |
| `title` required What to call it from now… | string | body |

### What comes back

| Field | Type |
| --- | --- |
| `id` The conversation id, which is how… | string |
| `sessionId` The provider session behind the last… | string |
| `title` What to call it: the first… | string |
| `status` What it is doing | "idle" | "running" | "awaiting" | "stopping" … (11) |
| `failure` Why the last turn failed, in… | string |
| `provider` Which model provider it runs on | string |
| `harness` Which agentic loop it runs on | "native" | "claude-code" |
| `model` What its last turn ran with | string |
| `effort` How hard that turn was told… | string |
| `thinking` Whether that turn showed its reasoning | boolean |
| `fast` Whether that turn asked for higher… | boolean |
| `tier` How hard its last turn looked… | "fast" | "standard" |
| `tierHold` Whether this conversation is pinned to… | boolean |
| `account` Which connected account paid for it | string |
| `branch` The branch its private copy works… | string |
| `autoLand` This conversation's own answer to whether… | boolean |
| `resumeAfterOutage` | boolean |
| `landRequested` A collaborator has asked a maintainer… | object |
| `email` Who asked | string |
| `name` Their display name | string |
| `at` When they asked, in milliseconds | number |
| `origin` Where the conversation came from when… | object |
| `automationId` | string |
| `provider` | string |
| `channelId` | string |
| `author` | string |
| `forkedFrom` The conversation this one was cut… | object |
| `conversationId` | string |
| `index` | integer |
| `files` | "then" | "now" |
| `base` The commit its private copy started… | string |
| `costUsd` What it has cost so far,… | number |
| `inputTokens` Tokens sent | number |
| `outputTokens` Tokens received | number |
| `contextTokens` How much of the window the… | number |
| `contextWindow` How large that window is | number |
| `activity` What it is doing at this… | object |
| `tool` The last tool it reached for | string |
| `target` What it reached for that tool… | string |
| `todo` The item on its own list… | string |
| `landedMessageDraft` The whole story of this merge's… | object |
| `startedAt` When the drafting began, in milliseconds | number |
| `steps` Each model that was asked, in… | object[] |
| `provider` Which provider was asked | string |
| `model` Which of its models | string |
| `status` How this one went | "asking" | "answered" | "refused" | "skipped" |
| `at` When it started being asked, in… | number |
| `ms` How long it took | number |
| `reason` Why it refused, in its own… | string |
| `outcome` How it ended | "written" | "failed" |
| `reason` The one-line account of a failure,… | string |
| `finishedAt` When it ended, in milliseconds | number |
| `landedMessage` What this conversation's merged work is… | object |
| `subject` One line saying what the merged… | string |
| `note` The same change said to somebody… | string |
| `breaking` What this change takes away, for… | string |
| `startedAt` When the running turn started, in… | number |
| `updatedAt` When it last did something, in… | number |
| `seenAt` When somebody last opened it, in… | number |
| `attention` Which kinds of waiting-for-you it is… | object |
| `plan` It has proposed a plan and… | boolean |
| `question` It has asked you something | boolean |
| `permission` It wants to use a tool… | boolean |
| `service` It wants to spend money on… | boolean |
| `capability` It needs something connected that is… | boolean |
| `conflict` Its work cannot be merged without… | boolean |
| `turns` Turns it has finished | number |
| `toolUses` Tools it has used, over its… | number |
| `subagents` Helper agents this one delegated to | object |
| `running` Helpers working right now | number |
| `total` Helpers it has started over its… | number |
| `diff` Everything it has written, measured from… | object |
| `files` Files touched | number |
| `insertions` Lines added | number |
| `deletions` Lines removed | number |
| `landedPresence` Present only when some of what… | object |
| `landed` Paths this conversation merged in | number |
| `present` How many of them are still… | number |
| `loop` The loop driving this conversation, if… | object |
| `state` How the loop is going | "running" | "done" | "exhausted" | "stalled" … (7) |
| `iteration` Which round it is on | integer |
| `maxIterations` How many rounds it will attempt… | integer |
| `goal` What it is looping towards | string |
| `workflow` The workflow run this conversation is… | object |
| `runId` The run this belongs to, which… | string |
| `name` The workflow's name | string |
| `step` Which step this conversation is on… | string |
| `index` This step's place in the workflow,… | integer |
| `total` How many steps the workflow has | integer |
| `archivedAt` When it was put away, in… | number |

Try it answered in this tab

curl

```bash
curl -X POST "$SANDBOX/agents/a1b2c3d4/rename" \
 -H "x-intentic-control: $INTENTIC_TOKEN" \
 -H "content-type: application/json" \
 -d '{"title":"Update the changelog"}'
```

TypeScript

```typescript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.agents.rename({
 "id": "a1b2c3d4",
 "title": "Update the changelog"
});
```

**POST`/agents/{id}/auto-land` Whether this conversation merges its work automatically**

Overrides the sandbox-wide setting for one conversation; clear it to go back to following the default. Deliberately allowed mid-turn, because the setting is read when the turn finishes, so flipping it while the agent works means exactly hold this piece of work for review.

### What you send

| Field | Type | Where |
| --- | --- | --- |
| `id` required Which conversation | string | address |
| `autoLand` required Whether its work merges automatically when… | boolean | null | body |

### What comes back

| Field | Type |
| --- | --- |
| `id` The conversation id, which is how… | string |
| `sessionId` The provider session behind the last… | string |
| `title` What to call it: the first… | string |
| `status` What it is doing | "idle" | "running" | "awaiting" | "stopping" … (11) |
| `failure` Why the last turn failed, in… | string |
| `provider` Which model provider it runs on | string |
| `harness` Which agentic loop it runs on | "native" | "claude-code" |
| `model` What its last turn ran with | string |
| `effort` How hard that turn was told… | string |
| `thinking` Whether that turn showed its reasoning | boolean |
| `fast` Whether that turn asked for higher… | boolean |
| `tier` How hard its last turn looked… | "fast" | "standard" |
| `tierHold` Whether this conversation is pinned to… | boolean |
| `account` Which connected account paid for it | string |
| `branch` The branch its private copy works… | string |
| `autoLand` This conversation's own answer to whether… | boolean |
| `resumeAfterOutage` | boolean |
| `landRequested` A collaborator has asked a maintainer… | object |
| `email` Who asked | string |
| `name` Their display name | string |
| `at` When they asked, in milliseconds | number |
| `origin` Where the conversation came from when… | object |
| `automationId` | string |
| `provider` | string |
| `channelId` | string |
| `author` | string |
| `forkedFrom` The conversation this one was cut… | object |
| `conversationId` | string |
| `index` | integer |
| `files` | "then" | "now" |
| `base` The commit its private copy started… | string |
| `costUsd` What it has cost so far,… | number |
| `inputTokens` Tokens sent | number |
| `outputTokens` Tokens received | number |
| `contextTokens` How much of the window the… | number |
| `contextWindow` How large that window is | number |
| `activity` What it is doing at this… | object |
| `tool` The last tool it reached for | string |
| `target` What it reached for that tool… | string |
| `todo` The item on its own list… | string |
| `landedMessageDraft` The whole story of this merge's… | object |
| `startedAt` When the drafting began, in milliseconds | number |
| `steps` Each model that was asked, in… | object[] |
| `provider` Which provider was asked | string |
| `model` Which of its models | string |
| `status` How this one went | "asking" | "answered" | "refused" | "skipped" |
| `at` When it started being asked, in… | number |
| `ms` How long it took | number |
| `reason` Why it refused, in its own… | string |
| `outcome` How it ended | "written" | "failed" |
| `reason` The one-line account of a failure,… | string |
| `finishedAt` When it ended, in milliseconds | number |
| `landedMessage` What this conversation's merged work is… | object |
| `subject` One line saying what the merged… | string |
| `note` The same change said to somebody… | string |
| `breaking` What this change takes away, for… | string |
| `startedAt` When the running turn started, in… | number |
| `updatedAt` When it last did something, in… | number |
| `seenAt` When somebody last opened it, in… | number |
| `attention` Which kinds of waiting-for-you it is… | object |
| `plan` It has proposed a plan and… | boolean |
| `question` It has asked you something | boolean |
| `permission` It wants to use a tool… | boolean |
| `service` It wants to spend money on… | boolean |
| `capability` It needs something connected that is… | boolean |
| `conflict` Its work cannot be merged without… | boolean |
| `turns` Turns it has finished | number |
| `toolUses` Tools it has used, over its… | number |
| `subagents` Helper agents this one delegated to | object |
| `running` Helpers working right now | number |
| `total` Helpers it has started over its… | number |
| `diff` Everything it has written, measured from… | object |
| `files` Files touched | number |
| `insertions` Lines added | number |
| `deletions` Lines removed | number |
| `landedPresence` Present only when some of what… | object |
| `landed` Paths this conversation merged in | number |
| `present` How many of them are still… | number |
| `loop` The loop driving this conversation, if… | object |
| `state` How the loop is going | "running" | "done" | "exhausted" | "stalled" … (7) |
| `iteration` Which round it is on | integer |
| `maxIterations` How many rounds it will attempt… | integer |
| `goal` What it is looping towards | string |
| `workflow` The workflow run this conversation is… | object |
| `runId` The run this belongs to, which… | string |
| `name` The workflow's name | string |
| `step` Which step this conversation is on… | string |
| `index` This step's place in the workflow,… | integer |
| `total` How many steps the workflow has | integer |
| `archivedAt` When it was put away, in… | number |

Try it answered in this tab

curl

```bash
curl -X POST "$SANDBOX/agents/a1b2c3d4/auto-land" \
 -H "x-intentic-control: $INTENTIC_TOKEN" \
 -H "content-type: application/json" \
 -d '{"autoLand":true}'
```

TypeScript

```typescript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.agents.autoLand({
 "id": "a1b2c3d4",
 "autoLand": true
});
```

**POST`/agents/{id}/resume-after-outage` Whether this conversation retries after a provider outage**

Overrides the sandbox-wide setting for one conversation; clear it to follow the default again. This is what the offer shown when a turn dies writes, because the press happens inside one conversation and honestly means finish this piece of work.

### What you send

| Field | Type | Where |
| --- | --- | --- |
| `id` required Which conversation | string | address |
| `resumeAfterOutage` required Whether it retries by itself when… | boolean | null | body |

### What comes back

| Field | Type |
| --- | --- |
| `id` The conversation id, which is how… | string |
| `sessionId` The provider session behind the last… | string |
| `title` What to call it: the first… | string |
| `status` What it is doing | "idle" | "running" | "awaiting" | "stopping" … (11) |
| `failure` Why the last turn failed, in… | string |
| `provider` Which model provider it runs on | string |
| `harness` Which agentic loop it runs on | "native" | "claude-code" |
| `model` What its last turn ran with | string |
| `effort` How hard that turn was told… | string |
| `thinking` Whether that turn showed its reasoning | boolean |
| `fast` Whether that turn asked for higher… | boolean |
| `tier` How hard its last turn looked… | "fast" | "standard" |
| `tierHold` Whether this conversation is pinned to… | boolean |
| `account` Which connected account paid for it | string |
| `branch` The branch its private copy works… | string |
| `autoLand` This conversation's own answer to whether… | boolean |
| `resumeAfterOutage` | boolean |
| `landRequested` A collaborator has asked a maintainer… | object |
| `email` Who asked | string |
| `name` Their display name | string |
| `at` When they asked, in milliseconds | number |
| `origin` Where the conversation came from when… | object |
| `automationId` | string |
| `provider` | string |
| `channelId` | string |
| `author` | string |
| `forkedFrom` The conversation this one was cut… | object |
| `conversationId` | string |
| `index` | integer |
| `files` | "then" | "now" |
| `base` The commit its private copy started… | string |
| `costUsd` What it has cost so far,… | number |
| `inputTokens` Tokens sent | number |
| `outputTokens` Tokens received | number |
| `contextTokens` How much of the window the… | number |
| `contextWindow` How large that window is | number |
| `activity` What it is doing at this… | object |
| `tool` The last tool it reached for | string |
| `target` What it reached for that tool… | string |
| `todo` The item on its own list… | string |
| `landedMessageDraft` The whole story of this merge's… | object |
| `startedAt` When the drafting began, in milliseconds | number |
| `steps` Each model that was asked, in… | object[] |
| `provider` Which provider was asked | string |
| `model` Which of its models | string |
| `status` How this one went | "asking" | "answered" | "refused" | "skipped" |
| `at` When it started being asked, in… | number |
| `ms` How long it took | number |
| `reason` Why it refused, in its own… | string |
| `outcome` How it ended | "written" | "failed" |
| `reason` The one-line account of a failure,… | string |
| `finishedAt` When it ended, in milliseconds | number |
| `landedMessage` What this conversation's merged work is… | object |
| `subject` One line saying what the merged… | string |
| `note` The same change said to somebody… | string |
| `breaking` What this change takes away, for… | string |
| `startedAt` When the running turn started, in… | number |
| `updatedAt` When it last did something, in… | number |
| `seenAt` When somebody last opened it, in… | number |
| `attention` Which kinds of waiting-for-you it is… | object |
| `plan` It has proposed a plan and… | boolean |
| `question` It has asked you something | boolean |
| `permission` It wants to use a tool… | boolean |
| `service` It wants to spend money on… | boolean |
| `capability` It needs something connected that is… | boolean |
| `conflict` Its work cannot be merged without… | boolean |
| `turns` Turns it has finished | number |
| `toolUses` Tools it has used, over its… | number |
| `subagents` Helper agents this one delegated to | object |
| `running` Helpers working right now | number |
| `total` Helpers it has started over its… | number |
| `diff` Everything it has written, measured from… | object |
| `files` Files touched | number |
| `insertions` Lines added | number |
| `deletions` Lines removed | number |
| `landedPresence` Present only when some of what… | object |
| `landed` Paths this conversation merged in | number |
| `present` How many of them are still… | number |
| `loop` The loop driving this conversation, if… | object |
| `state` How the loop is going | "running" | "done" | "exhausted" | "stalled" … (7) |
| `iteration` Which round it is on | integer |
| `maxIterations` How many rounds it will attempt… | integer |
| `goal` What it is looping towards | string |
| `workflow` The workflow run this conversation is… | object |
| `runId` The run this belongs to, which… | string |
| `name` The workflow's name | string |
| `step` Which step this conversation is on… | string |
| `index` This step's place in the workflow,… | integer |
| `total` How many steps the workflow has | integer |
| `archivedAt` When it was put away, in… | number |

Try it answered in this tab

curl

```bash
curl -X POST "$SANDBOX/agents/a1b2c3d4/resume-after-outage" \
 -H "x-intentic-control: $INTENTIC_TOKEN" \
 -H "content-type: application/json" \
 -d '{"resumeAfterOutage":true}'
```

TypeScript

```typescript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.agents.resumeAfterOutage({
 "id": "a1b2c3d4",
 "resumeAfterOutage": true
});
```

**POST`/agents/{id}/seen` Mark a conversation read**

Stamps the read marker behind the unread badge on one card. Allowed while the conversation is working, and reading never counts as activity.

### What you send

| Field | Type | Where |
| --- | --- | --- |
| `id` required Which conversation | string | address |

### What comes back

| Field | Type |
| --- | --- |
| `id` The conversation id, which is how… | string |
| `sessionId` The provider session behind the last… | string |
| `title` What to call it: the first… | string |
| `status` What it is doing | "idle" | "running" | "awaiting" | "stopping" … (11) |
| `failure` Why the last turn failed, in… | string |
| `provider` Which model provider it runs on | string |
| `harness` Which agentic loop it runs on | "native" | "claude-code" |
| `model` What its last turn ran with | string |
| `effort` How hard that turn was told… | string |
| `thinking` Whether that turn showed its reasoning | boolean |
| `fast` Whether that turn asked for higher… | boolean |
| `tier` How hard its last turn looked… | "fast" | "standard" |
| `tierHold` Whether this conversation is pinned to… | boolean |
| `account` Which connected account paid for it | string |
| `branch` The branch its private copy works… | string |
| `autoLand` This conversation's own answer to whether… | boolean |
| `resumeAfterOutage` | boolean |
| `landRequested` A collaborator has asked a maintainer… | object |
| `email` Who asked | string |
| `name` Their display name | string |
| `at` When they asked, in milliseconds | number |
| `origin` Where the conversation came from when… | object |
| `automationId` | string |
| `provider` | string |
| `channelId` | string |
| `author` | string |
| `forkedFrom` The conversation this one was cut… | object |
| `conversationId` | string |
| `index` | integer |
| `files` | "then" | "now" |
| `base` The commit its private copy started… | string |
| `costUsd` What it has cost so far,… | number |
| `inputTokens` Tokens sent | number |
| `outputTokens` Tokens received | number |
| `contextTokens` How much of the window the… | number |
| `contextWindow` How large that window is | number |
| `activity` What it is doing at this… | object |
| `tool` The last tool it reached for | string |
| `target` What it reached for that tool… | string |
| `todo` The item on its own list… | string |
| `landedMessageDraft` The whole story of this merge's… | object |
| `startedAt` When the drafting began, in milliseconds | number |
| `steps` Each model that was asked, in… | object[] |
| `provider` Which provider was asked | string |
| `model` Which of its models | string |
| `status` How this one went | "asking" | "answered" | "refused" | "skipped" |
| `at` When it started being asked, in… | number |
| `ms` How long it took | number |
| `reason` Why it refused, in its own… | string |
| `outcome` How it ended | "written" | "failed" |
| `reason` The one-line account of a failure,… | string |
| `finishedAt` When it ended, in milliseconds | number |
| `landedMessage` What this conversation's merged work is… | object |
| `subject` One line saying what the merged… | string |
| `note` The same change said to somebody… | string |
| `breaking` What this change takes away, for… | string |
| `startedAt` When the running turn started, in… | number |
| `updatedAt` When it last did something, in… | number |
| `seenAt` When somebody last opened it, in… | number |
| `attention` Which kinds of waiting-for-you it is… | object |
| `plan` It has proposed a plan and… | boolean |
| `question` It has asked you something | boolean |
| `permission` It wants to use a tool… | boolean |
| `service` It wants to spend money on… | boolean |
| `capability` It needs something connected that is… | boolean |
| `conflict` Its work cannot be merged without… | boolean |
| `turns` Turns it has finished | number |
| `toolUses` Tools it has used, over its… | number |
| `subagents` Helper agents this one delegated to | object |
| `running` Helpers working right now | number |
| `total` Helpers it has started over its… | number |
| `diff` Everything it has written, measured from… | object |
| `files` Files touched | number |
| `insertions` Lines added | number |
| `deletions` Lines removed | number |
| `landedPresence` Present only when some of what… | object |
| `landed` Paths this conversation merged in | number |
| `present` How many of them are still… | number |
| `loop` The loop driving this conversation, if… | object |
| `state` How the loop is going | "running" | "done" | "exhausted" | "stalled" … (7) |
| `iteration` Which round it is on | integer |
| `maxIterations` How many rounds it will attempt… | integer |
| `goal` What it is looping towards | string |
| `workflow` The workflow run this conversation is… | object |
| `runId` The run this belongs to, which… | string |
| `name` The workflow's name | string |
| `step` Which step this conversation is on… | string |
| `index` This step's place in the workflow,… | integer |
| `total` How many steps the workflow has | integer |
| `archivedAt` When it was put away, in… | number |

Try it answered in this tab

curl

```bash
curl -X POST "$SANDBOX/agents/a1b2c3d4/seen" \
 -H "x-intentic-control: $INTENTIC_TOKEN"
```

TypeScript

```typescript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.agents.seen({
 "id": "a1b2c3d4"
});
```

**POST`/agents/seen` Mark every conversation read**

Clears the unread badge across the whole fleet at once, and hands the refreshed list back.

### What you send

Nothing. Call it as it is.

### What comes back

| Field | Type |
| --- | --- |
| `agents` The conversations | object[] |
| `id` The conversation id, which is how… | string |
| `sessionId` The provider session behind the last… | string |
| `title` What to call it: the first… | string |
| `status` What it is doing | "idle" | "running" | "awaiting" | "stopping" … (11) |
| `failure` Why the last turn failed, in… | string |
| `provider` Which model provider it runs on | string |
| `harness` Which agentic loop it runs on | "native" | "claude-code" |
| `model` What its last turn ran with | string |
| `effort` How hard that turn was told… | string |
| `thinking` Whether that turn showed its reasoning | boolean |
| `fast` Whether that turn asked for higher… | boolean |
| `tier` How hard its last turn looked… | "fast" | "standard" |
| `tierHold` Whether this conversation is pinned to… | boolean |
| `account` Which connected account paid for it | string |
| `branch` The branch its private copy works… | string |
| `autoLand` This conversation's own answer to whether… | boolean |
| `resumeAfterOutage` | boolean |
| `landRequested` A collaborator has asked a maintainer… | object |
| `email` Who asked | string |
| `name` Their display name | string |
| `at` When they asked, in milliseconds | number |
| `origin` Where the conversation came from when… | object |
| `automationId` | string |
| `provider` | string |
| `channelId` | string |
| `author` | string |
| `forkedFrom` The conversation this one was cut… | object |
| `conversationId` | string |
| `index` | integer |
| `files` | "then" | "now" |
| `base` The commit its private copy started… | string |
| `costUsd` What it has cost so far,… | number |
| `inputTokens` Tokens sent | number |
| `outputTokens` Tokens received | number |
| `contextTokens` How much of the window the… | number |
| `contextWindow` How large that window is | number |
| `activity` What it is doing at this… | object |
| `tool` The last tool it reached for | string |
| `target` What it reached for that tool… | string |
| `todo` The item on its own list… | string |
| `landedMessageDraft` The whole story of this merge's… | object |
| `startedAt` When the drafting began, in milliseconds | number |
| `steps` Each model that was asked, in… | object[] |
| `provider` Which provider was asked | string |
| `model` Which of its models | string |
| `status` How this one went | "asking" | "answered" | "refused" | "skipped" |
| `at` When it started being asked, in… | number |
| `ms` How long it took | number |
| `reason` Why it refused, in its own… | string |
| `outcome` How it ended | "written" | "failed" |
| `reason` The one-line account of a failure,… | string |
| `finishedAt` When it ended, in milliseconds | number |
| `landedMessage` What this conversation's merged work is… | object |
| `subject` One line saying what the merged… | string |
| `note` The same change said to somebody… | string |
| `breaking` What this change takes away, for… | string |
| `startedAt` When the running turn started, in… | number |
| `updatedAt` When it last did something, in… | number |
| `seenAt` When somebody last opened it, in… | number |
| `attention` Which kinds of waiting-for-you it is… | object |
| `plan` It has proposed a plan and… | boolean |
| `question` It has asked you something | boolean |
| `permission` It wants to use a tool… | boolean |
| `service` It wants to spend money on… | boolean |
| `capability` It needs something connected that is… | boolean |
| `conflict` Its work cannot be merged without… | boolean |
| `turns` Turns it has finished | number |
| `toolUses` Tools it has used, over its… | number |
| `subagents` Helper agents this one delegated to | object |
| `running` Helpers working right now | number |
| `total` Helpers it has started over its… | number |
| `diff` Everything it has written, measured from… | object |
| `files` Files touched | number |
| `insertions` Lines added | number |
| `deletions` Lines removed | number |
| `landedPresence` Present only when some of what… | object |
| `landed` Paths this conversation merged in | number |
| `present` How many of them are still… | number |
| `loop` The loop driving this conversation, if… | object |
| `state` How the loop is going | "running" | "done" | "exhausted" | "stalled" … (7) |
| `iteration` Which round it is on | integer |
| `maxIterations` How many rounds it will attempt… | integer |
| `goal` What it is looping towards | string |
| `workflow` The workflow run this conversation is… | object |
| `runId` The run this belongs to, which… | string |
| `name` The workflow's name | string |
| `step` Which step this conversation is on… | string |
| `index` This step's place in the workflow,… | integer |
| `total` How many steps the workflow has | integer |
| `archivedAt` When it was put away, in… | number |
| `rev` Which version of the fleet this… | number |
| `held` Automations waiting at the door for… | object[] |
| `id` This waiting item's own id, which… | string |
| `automationId` Which automation it came from | string |
| `payload` What set it off, kept whole… | string |
| `origin` Where the message came from, kept… | object |
| `automationId` | string |
| `provider` | string |
| `channelId` | string |
| `author` | string |
| `title` What the conversation would be called | string |
| `conversationId` The thread this belongs to, when… | string |
| `sessionId` The provider session that thread last… | string |
| `createdAt` When it started waiting, in milliseconds | number |
| `autoRunAt` When it goes ahead on its… | number |

Try it answered in this tab

curl

```bash
curl -X POST "$SANDBOX/agents/seen" \
 -H "x-intentic-control: $INTENTIC_TOKEN"
```

TypeScript

```typescript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.agents.seenAll();
```

**GET`/agents/{id}/diff` Everything a conversation has changed**

One flat set of changed files per repo, measured against where each repo stood when the conversation started, with every file flagged as already merged or not. Not the staged-and-unstaged shape a working copy has, because nobody ever checks this branch out to stage into it.

### What you send

| Field | Type | Where |
| --- | --- | --- |
| `id` required Which conversation | string | address |

### What comes back

| Field | Type |
| --- | --- |
| `repos` One entry per repository the conversation… | object[] |
| `repo` Which repository | string |
| `branch` The branch this conversation's work sits… | string |
| `changes` What it changed there | object[] |
| `path` The path, relative to the repository… | string |
| `status` What happened to it | "added" | "modified" | "deleted" | "renamed" … (6) |
| `from` Where a renamed file came from | string |
| `additions` Lines added | number |
| `deletions` Lines removed | number |
| `landed` Whether this change is already in… | boolean |
| `modules` The packages of the tree these… | object[] |
| `dir` Where the package lives, relative to… | string |
| `name` The name the package declares for… | string |
| `conflicts` Why the last merge refused, when… | object[] |
| `repo` Which repository | string |
| `paths` The files that genuinely would not… | object[] |
| `path` Which file | string |
| `reason` Why it would not merge, and… | "workspace" | "diverged" | "binary" |
| `clean` How many files would apply regardless,… | number |
| `mainBranch` The branch your own checkout is… | string |

Try it answered in this tab

curl

```bash
curl "$SANDBOX/agents/a1b2c3d4/diff" \
 -H "x-intentic-control: $INTENTIC_TOKEN"
```

TypeScript

```typescript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.agents.diff({
 "id": "a1b2c3d4"
});
```

**GET`/agents/{id}/{repo}/file-diff` One file's before and after in a conversation's work**

Both sides of a single file: what it held when the conversation started and what it holds on its branch now.

### What you send

| Field | Type | Where |
| --- | --- | --- |
| `id` required Which conversation | string | address |
| `repo` required Which repository | string | address |
| `path` required Which file, relative to that repository | string | query |

### What comes back

| Field | Type |
| --- | --- |
| `before` The whole file as it was | string |
| `after` The whole file as it is… | string |
| `binary` The file is not text, so… | boolean |
| `truncated` The file was too large to… | boolean |

Try it answered in this tab

curl

```bash
curl "$SANDBOX/agents/a1b2c3d4/root/file-diff?path=src%2Fapp.ts" \
 -H "x-intentic-control: $INTENTIC_TOKEN"
```

TypeScript

```typescript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.agents.fileDiff({
 "id": "a1b2c3d4",
 "repo": "root",
 "path": "src/app.ts"
});
```

**POST`/agents/{id}/land` Merge a conversation's work into the workspace**

Brings the conversation's branches into the main tree, one repo at a time. A conflict is reported rather than raised and nothing is lost when it fails. Refused while a turn is running, and refused for a conversation that works directly in the shared tree, which has nothing to merge.

### What you send

| Field | Type | Where |
| --- | --- | --- |
| `id` required Which conversation's work to merge | string | address |
| `mode` How to apply it | "check" | "merge" | "measure" | body |
| `span` How much of the work to… | "cumulative" | "outstanding" | body |
| `force` Go ahead despite a check that… | boolean | body |

### What comes back

| Field | Type |
| --- | --- |
| `landed` Whether anything was applied | boolean |
| `conflicts` What stopped it, per repository | object[] |
| `repo` Which repository | string |
| `paths` The files that genuinely would not… | object[] |
| `path` Which file | string |
| `reason` Why it would not merge, and… | "workspace" | "diverged" | "binary" |
| `clean` How many files would apply regardless,… | number |
| `mainBranch` The branch your own checkout is… | string |
| `resolving` Files left half-merged, when you asked… | object[] |
| `repo` Which repository | string |
| `paths` Which files now hold conflict markers… | string[] |
| `held` Nothing was applied and nothing failed:… | boolean |

Try it answered in this tab

curl

```bash
curl -X POST "$SANDBOX/agents/a1b2c3d4/land" \
 -H "x-intentic-control: $INTENTIC_TOKEN" \
 -H "content-type: application/json" \
 -d '{"mode":"check","span":"cumulative","force":false}'
```

TypeScript

```typescript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.agents.land({
 "id": "a1b2c3d4",
 "mode": "check",
 "span": "cumulative",
 "force": false
});
```

**POST`/agents/{id}/request-land` Ask a maintainer to merge this work**

For a collaborator who is not allowed to merge: marks the conversation as waiting for review, with who asked. The request shows on every maintainer's board and clears when somebody merges or discards it.

### What you send

| Field | Type | Where |
| --- | --- | --- |
| `id` required Which conversation | string | address |

### What comes back

| Field | Type |
| --- | --- |
| `id` The conversation id, which is how… | string |
| `sessionId` The provider session behind the last… | string |
| `title` What to call it: the first… | string |
| `status` What it is doing | "idle" | "running" | "awaiting" | "stopping" … (11) |
| `failure` Why the last turn failed, in… | string |
| `provider` Which model provider it runs on | string |
| `harness` Which agentic loop it runs on | "native" | "claude-code" |
| `model` What its last turn ran with | string |
| `effort` How hard that turn was told… | string |
| `thinking` Whether that turn showed its reasoning | boolean |
| `fast` Whether that turn asked for higher… | boolean |
| `tier` How hard its last turn looked… | "fast" | "standard" |
| `tierHold` Whether this conversation is pinned to… | boolean |
| `account` Which connected account paid for it | string |
| `branch` The branch its private copy works… | string |
| `autoLand` This conversation's own answer to whether… | boolean |
| `resumeAfterOutage` | boolean |
| `landRequested` A collaborator has asked a maintainer… | object |
| `email` Who asked | string |
| `name` Their display name | string |
| `at` When they asked, in milliseconds | number |
| `origin` Where the conversation came from when… | object |
| `automationId` | string |
| `provider` | string |
| `channelId` | string |
| `author` | string |
| `forkedFrom` The conversation this one was cut… | object |
| `conversationId` | string |
| `index` | integer |
| `files` | "then" | "now" |
| `base` The commit its private copy started… | string |
| `costUsd` What it has cost so far,… | number |
| `inputTokens` Tokens sent | number |
| `outputTokens` Tokens received | number |
| `contextTokens` How much of the window the… | number |
| `contextWindow` How large that window is | number |
| `activity` What it is doing at this… | object |
| `tool` The last tool it reached for | string |
| `target` What it reached for that tool… | string |
| `todo` The item on its own list… | string |
| `landedMessageDraft` The whole story of this merge's… | object |
| `startedAt` When the drafting began, in milliseconds | number |
| `steps` Each model that was asked, in… | object[] |
| `provider` Which provider was asked | string |
| `model` Which of its models | string |
| `status` How this one went | "asking" | "answered" | "refused" | "skipped" |
| `at` When it started being asked, in… | number |
| `ms` How long it took | number |
| `reason` Why it refused, in its own… | string |
| `outcome` How it ended | "written" | "failed" |
| `reason` The one-line account of a failure,… | string |
| `finishedAt` When it ended, in milliseconds | number |
| `landedMessage` What this conversation's merged work is… | object |
| `subject` One line saying what the merged… | string |
| `note` The same change said to somebody… | string |
| `breaking` What this change takes away, for… | string |
| `startedAt` When the running turn started, in… | number |
| `updatedAt` When it last did something, in… | number |
| `seenAt` When somebody last opened it, in… | number |
| `attention` Which kinds of waiting-for-you it is… | object |
| `plan` It has proposed a plan and… | boolean |
| `question` It has asked you something | boolean |
| `permission` It wants to use a tool… | boolean |
| `service` It wants to spend money on… | boolean |
| `capability` It needs something connected that is… | boolean |
| `conflict` Its work cannot be merged without… | boolean |
| `turns` Turns it has finished | number |
| `toolUses` Tools it has used, over its… | number |
| `subagents` Helper agents this one delegated to | object |
| `running` Helpers working right now | number |
| `total` Helpers it has started over its… | number |
| `diff` Everything it has written, measured from… | object |
| `files` Files touched | number |
| `insertions` Lines added | number |
| `deletions` Lines removed | number |
| `landedPresence` Present only when some of what… | object |
| `landed` Paths this conversation merged in | number |
| `present` How many of them are still… | number |
| `loop` The loop driving this conversation, if… | object |
| `state` How the loop is going | "running" | "done" | "exhausted" | "stalled" … (7) |
| `iteration` Which round it is on | integer |
| `maxIterations` How many rounds it will attempt… | integer |
| `goal` What it is looping towards | string |
| `workflow` The workflow run this conversation is… | object |
| `runId` The run this belongs to, which… | string |
| `name` The workflow's name | string |
| `step` Which step this conversation is on… | string |
| `index` This step's place in the workflow,… | integer |
| `total` How many steps the workflow has | integer |
| `archivedAt` When it was put away, in… | number |

Try it answered in this tab

curl

```bash
curl -X POST "$SANDBOX/agents/a1b2c3d4/request-land" \
 -H "x-intentic-control: $INTENTIC_TOKEN"
```

TypeScript

```typescript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.agents.requestLand({
 "id": "a1b2c3d4"
});
```

**POST`/agents/{id}/discard` Throw a conversation's work away**

Deletes the conversation's working copies, its branches and its entry. Nothing is kept. Refused while a turn is running, and refused for a conversation working in the shared tree.

### What you send

| Field | Type | Where |
| --- | --- | --- |
| `id` required Which conversation | string | address |

### What comes back

| Field | Type |
| --- | --- |
| `ok` Always true | true |

Try it answered in this tab

curl

```bash
curl -X POST "$SANDBOX/agents/a1b2c3d4/discard" \
 -H "x-intentic-control: $INTENTIC_TOKEN"
```

TypeScript

```typescript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.agents.discard({
 "id": "a1b2c3d4"
});
```

**POST`/agents/archive` Put conversations away**

The gentle counterpart to discarding. Commits whatever the conversation still has in progress onto its own branch, releases its working copy, and keeps the entry and the record. It leaves the live fleet and joins the archive. Refused for a conversation that is running.

### What you send

| Field | Type | Where |
| --- | --- | --- |
| `ids` Which conversations to put away | string[] | body |

### What comes back

| Field | Type |
| --- | --- |
| `moved` What actually moved, whole, rather than… | object[] |
| `id` The conversation id, which is how… | string |
| `sessionId` The provider session behind the last… | string |
| `title` What to call it: the first… | string |
| `status` What it is doing | "idle" | "running" | "awaiting" | "stopping" … (11) |
| `failure` Why the last turn failed, in… | string |
| `provider` Which model provider it runs on | string |
| `harness` Which agentic loop it runs on | "native" | "claude-code" |
| `model` What its last turn ran with | string |
| `effort` How hard that turn was told… | string |
| `thinking` Whether that turn showed its reasoning | boolean |
| `fast` Whether that turn asked for higher… | boolean |
| `tier` How hard its last turn looked… | "fast" | "standard" |
| `tierHold` Whether this conversation is pinned to… | boolean |
| `account` Which connected account paid for it | string |
| `branch` The branch its private copy works… | string |
| `autoLand` This conversation's own answer to whether… | boolean |
| `resumeAfterOutage` | boolean |
| `landRequested` A collaborator has asked a maintainer… | object |
| `email` Who asked | string |
| `name` Their display name | string |
| `at` When they asked, in milliseconds | number |
| `origin` Where the conversation came from when… | object |
| `automationId` | string |
| `provider` | string |
| `channelId` | string |
| `author` | string |
| `forkedFrom` The conversation this one was cut… | object |
| `conversationId` | string |
| `index` | integer |
| `files` | "then" | "now" |
| `base` The commit its private copy started… | string |
| `costUsd` What it has cost so far,… | number |
| `inputTokens` Tokens sent | number |
| `outputTokens` Tokens received | number |
| `contextTokens` How much of the window the… | number |
| `contextWindow` How large that window is | number |
| `activity` What it is doing at this… | object |
| `tool` The last tool it reached for | string |
| `target` What it reached for that tool… | string |
| `todo` The item on its own list… | string |
| `landedMessageDraft` The whole story of this merge's… | object |
| `startedAt` When the drafting began, in milliseconds | number |
| `steps` Each model that was asked, in… | object[] |
| `provider` Which provider was asked | string |
| `model` Which of its models | string |
| `status` How this one went | "asking" | "answered" | "refused" | "skipped" |
| `at` When it started being asked, in… | number |
| `ms` How long it took | number |
| `reason` Why it refused, in its own… | string |
| `outcome` How it ended | "written" | "failed" |
| `reason` The one-line account of a failure,… | string |
| `finishedAt` When it ended, in milliseconds | number |
| `landedMessage` What this conversation's merged work is… | object |
| `subject` One line saying what the merged… | string |
| `note` The same change said to somebody… | string |
| `breaking` What this change takes away, for… | string |
| `startedAt` When the running turn started, in… | number |
| `updatedAt` When it last did something, in… | number |
| `seenAt` When somebody last opened it, in… | number |
| `attention` Which kinds of waiting-for-you it is… | object |
| `plan` It has proposed a plan and… | boolean |
| `question` It has asked you something | boolean |
| `permission` It wants to use a tool… | boolean |
| `service` It wants to spend money on… | boolean |
| `capability` It needs something connected that is… | boolean |
| `conflict` Its work cannot be merged without… | boolean |
| `turns` Turns it has finished | number |
| `toolUses` Tools it has used, over its… | number |
| `subagents` Helper agents this one delegated to | object |
| `running` Helpers working right now | number |
| `total` Helpers it has started over its… | number |
| `diff` Everything it has written, measured from… | object |
| `files` Files touched | number |
| `insertions` Lines added | number |
| `deletions` Lines removed | number |
| `landedPresence` Present only when some of what… | object |
| `landed` Paths this conversation merged in | number |
| `present` How many of them are still… | number |
| `loop` The loop driving this conversation, if… | object |
| `state` How the loop is going | "running" | "done" | "exhausted" | "stalled" … (7) |
| `iteration` Which round it is on | integer |
| `maxIterations` How many rounds it will attempt… | integer |
| `goal` What it is looping towards | string |
| `workflow` The workflow run this conversation is… | object |
| `runId` The run this belongs to, which… | string |
| `name` The workflow's name | string |
| `step` Which step this conversation is on… | string |
| `index` This step's place in the workflow,… | integer |
| `total` How many steps the workflow has | integer |
| `archivedAt` When it was put away, in… | number |
| `rev` The version of the fleet that… | number |
| `failed` The conversations this press could not… | object[] |
| `id` Which conversation stayed on the board | string |
| `reason` Why its working copy could not… | string |

Try it answered in this tab

curl

```bash
curl -X POST "$SANDBOX/agents/archive" \
 -H "x-intentic-control: $INTENTIC_TOKEN" \
 -H "content-type: application/json" \
 -d '{"ids":["a1b2c3d4","e5f6a7b8"]}'
```

TypeScript

```typescript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.agents.archive({
 "ids": [
 "a1b2c3d4",
 "e5f6a7b8"
 ]
});
```

**POST`/agents/unarchive` Bring conversations back**

Returns archived conversations to the live fleet. The next turn picks up a fresh working copy from the branch that was kept.

### What you send

| Field | Type | Where |
| --- | --- | --- |
| `ids` required Which conversations | string[] | body |

### What comes back

| Field | Type |
| --- | --- |
| `moved` What actually moved, whole, rather than… | object[] |
| `id` The conversation id, which is how… | string |
| `sessionId` The provider session behind the last… | string |
| `title` What to call it: the first… | string |
| `status` What it is doing | "idle" | "running" | "awaiting" | "stopping" … (11) |
| `failure` Why the last turn failed, in… | string |
| `provider` Which model provider it runs on | string |
| `harness` Which agentic loop it runs on | "native" | "claude-code" |
| `model` What its last turn ran with | string |
| `effort` How hard that turn was told… | string |
| `thinking` Whether that turn showed its reasoning | boolean |
| `fast` Whether that turn asked for higher… | boolean |
| `tier` How hard its last turn looked… | "fast" | "standard" |
| `tierHold` Whether this conversation is pinned to… | boolean |
| `account` Which connected account paid for it | string |
| `branch` The branch its private copy works… | string |
| `autoLand` This conversation's own answer to whether… | boolean |
| `resumeAfterOutage` | boolean |
| `landRequested` A collaborator has asked a maintainer… | object |
| `email` Who asked | string |
| `name` Their display name | string |
| `at` When they asked, in milliseconds | number |
| `origin` Where the conversation came from when… | object |
| `automationId` | string |
| `provider` | string |
| `channelId` | string |
| `author` | string |
| `forkedFrom` The conversation this one was cut… | object |
| `conversationId` | string |
| `index` | integer |
| `files` | "then" | "now" |
| `base` The commit its private copy started… | string |
| `costUsd` What it has cost so far,… | number |
| `inputTokens` Tokens sent | number |
| `outputTokens` Tokens received | number |
| `contextTokens` How much of the window the… | number |
| `contextWindow` How large that window is | number |
| `activity` What it is doing at this… | object |
| `tool` The last tool it reached for | string |
| `target` What it reached for that tool… | string |
| `todo` The item on its own list… | string |
| `landedMessageDraft` The whole story of this merge's… | object |
| `startedAt` When the drafting began, in milliseconds | number |
| `steps` Each model that was asked, in… | object[] |
| `provider` Which provider was asked | string |
| `model` Which of its models | string |
| `status` How this one went | "asking" | "answered" | "refused" | "skipped" |
| `at` When it started being asked, in… | number |
| `ms` How long it took | number |
| `reason` Why it refused, in its own… | string |
| `outcome` How it ended | "written" | "failed" |
| `reason` The one-line account of a failure,… | string |
| `finishedAt` When it ended, in milliseconds | number |
| `landedMessage` What this conversation's merged work is… | object |
| `subject` One line saying what the merged… | string |
| `note` The same change said to somebody… | string |
| `breaking` What this change takes away, for… | string |
| `startedAt` When the running turn started, in… | number |
| `updatedAt` When it last did something, in… | number |
| `seenAt` When somebody last opened it, in… | number |
| `attention` Which kinds of waiting-for-you it is… | object |
| `plan` It has proposed a plan and… | boolean |
| `question` It has asked you something | boolean |
| `permission` It wants to use a tool… | boolean |
| `service` It wants to spend money on… | boolean |
| `capability` It needs something connected that is… | boolean |
| `conflict` Its work cannot be merged without… | boolean |
| `turns` Turns it has finished | number |
| `toolUses` Tools it has used, over its… | number |
| `subagents` Helper agents this one delegated to | object |
| `running` Helpers working right now | number |
| `total` Helpers it has started over its… | number |
| `diff` Everything it has written, measured from… | object |
| `files` Files touched | number |
| `insertions` Lines added | number |
| `deletions` Lines removed | number |
| `landedPresence` Present only when some of what… | object |
| `landed` Paths this conversation merged in | number |
| `present` How many of them are still… | number |
| `loop` The loop driving this conversation, if… | object |
| `state` How the loop is going | "running" | "done" | "exhausted" | "stalled" … (7) |
| `iteration` Which round it is on | integer |
| `maxIterations` How many rounds it will attempt… | integer |
| `goal` What it is looping towards | string |
| `workflow` The workflow run this conversation is… | object |
| `runId` The run this belongs to, which… | string |
| `name` The workflow's name | string |
| `step` Which step this conversation is on… | string |
| `index` This step's place in the workflow,… | integer |
| `total` How many steps the workflow has | integer |
| `archivedAt` When it was put away, in… | number |
| `rev` The version of the fleet that… | number |

Try it answered in this tab

curl

```bash
curl -X POST "$SANDBOX/agents/unarchive" \
 -H "x-intentic-control: $INTENTIC_TOKEN" \
 -H "content-type: application/json" \
 -d '{"ids":["a1b2c3d4","e5f6a7b8"]}'
```

TypeScript

```typescript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.agents.unarchive({
 "ids": [
 "a1b2c3d4",
 "e5f6a7b8"
 ]
});
```

**POST`/agents/purge` Empty the archive for good**

Discards every conversation already in the archive: working copies, branches and entries. The whole archive rather than a chosen few, because the archive is the pile somebody has already decided is over. A teardown that fails on one conversation leaves that one behind instead of taking the rest down with it.

### What you send

Nothing. Call it as it is.

### What comes back

| Field | Type |
| --- | --- |
| `removed` Which conversations were deleted, as ids | string[] |

Try it answered in this tab

curl

```bash
curl -X POST "$SANDBOX/agents/purge" \
 -H "x-intentic-control: $INTENTIC_TOKEN"
```

TypeScript

```typescript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.agents.purge();
```

More in Agents

[Previous ← One agent](https://intentic.dev/api/agent/)[Next Past sessions →](https://intentic.dev/api/sessions/)