# Orchestration: Vault & Import

**Page:** api/agent/orchestration/vault-import

[Download Raw Markdown](./api/agent/orchestration/vault-import.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



## Overview

The Orchestration Vault & Import API manages the **portable Master TODO state** — synchronizing TODOs to/from Hoody Vault and importing repositories across workspaces. Use these endpoints to discover vault-stored TODOs, sync local snapshots, start a repository import job, and poll import progress.

## Import Jobs

### `POST /api/v1/workspaces/{workspaceID}/orchestration/import`

Start a repository import into the workspace. The call returns immediately with an `importJobID` that you can poll for status.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | The target workspace ID |

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `repoUrl` | string | Yes | The URL of the repository to import (min length 1) |

### SDK Example

```ts
const { importJobID, todoID } = await client.agent.orchestration.startImport({
  workspaceID: "ws_prod_42",
  data: {
    repoUrl: "https://github.com/hoody/monorepo.git"
  }
});
```

### Response



```json
{
  "importJobID": "imp_01HF8Z3Q5K3VCD7Y7N8PQRSTA4",
  "todoID": "todo_01HF8Z3Q5K3VCD7Y7N8PQRSTA5"
}
```


```json
{
  "data": {},
  "errors": [
    {
      "propertyNames": ["repoUrl"],
      "message": "repoUrl must be a non-empty string"
    }
  ],
  "success": false
}
```



---

### `GET /api/v1/workspaces/{workspaceID}/orchestration/import/{jobID}`

Get the current status of a previously-started import job.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | The workspace ID |
| `jobID` | path | string | Yes | The import job ID returned by the start-import call |

### SDK Example

```ts
const job = await client.agent.orchestration.getImportStatus({
  workspaceID: "ws_prod_42",
  jobID: "imp_01HF8Z3Q5K3VCD7Y7N8PQRSTA4"
});

console.log(job.status, job.progress);
```

### Response



```json
{
  "id": "imp_01HF8Z3Q5K3VCD7Y7N8PQRSTA4",
  "status": "running",
  "progress": 42,
  "error": ""
}
```

`status` is one of `running`, `completed`, or `failed`. `error` is populated only when `status` is `failed`.


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "Import job not found"
  }
}
```



## Vault Sync & Import

### `POST /api/v1/workspaces/{workspaceID}/orchestration/vault/sync`

Sync the local Master TODO snapshot for the workspace to Hoody Vault. This pushes the current state so it can be discovered and imported into other workspaces later.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | The workspace whose snapshot should be synced |

### SDK Example

```ts
const result = await client.agent.orchestration.vaultSync({
  workspaceID: "ws_prod_42"
});

if (result.synced) {
  console.log("Snapshot uploaded to Vault");
}
```

### Response



```json
{
  "synced": true
}
```


```json
{
  "data": {},
  "errors": [
    {
      "propertyNames": ["workspaceID"],
      "message": "Workspace not eligible for vault sync"
    }
  ],
  "success": false
}
```



---

### `GET /api/v1/workspaces/{workspaceID}/orchestration/vault/discover`

Discover all Master TODOs currently stored in Hoody Vault. The result lists every portable TODO regardless of which workspace originally produced it.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | The workspace performing the discovery (used for scoping) |

### SDK Example

```ts
const { todos } = await client.agent.orchestration.vaultDiscover({
  workspaceID: "ws_prod_42"
});

for (const t of todos) {
  console.log(t.key, t.workspaceID, t.sizeBytes, t.updatedAt);
}
```

### Response



```json
{
  "todos": [
    {
      "key": "vault/todo/01HF8Z3Q5K3VCD7Y7N8PQRSTA5.json",
      "workspaceID": "ws_prod_42",
      "sizeBytes": 184320,
      "updatedAt": "2026-01-12T18:24:55.812Z"
    },
    {
      "key": "vault/todo/01HF902B1YV2HJ6SX0Z4Q7NMTE.json",
      "workspaceID": "ws_staging_07",
      "sizeBytes": 92104,
      "updatedAt": "2026-01-11T09:02:14.001Z"
    }
  ]
}
```



---

### `POST /api/v1/workspaces/{workspaceID}/orchestration/vault/import`

Import a Master TODO from Hoody Vault into a local workspace. Use the `key` from a prior `discover` call to identify the source snapshot, and `sourceWorkspaceID` to specify its origin. If `targetWorkspaceID` is omitted, the import lands in the workspace from the path.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | The authenticated workspace performing the import |

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `sourceWorkspaceID` | string | Yes | The workspace that produced the vault snapshot (min length 1) |
| `targetWorkspaceID` | string | No | The destination workspace ID (min length 1). Defaults to the path `workspaceID` |

### SDK Example

```ts
const result = await client.agent.orchestration.vaultImport({
  workspaceID: "ws_prod_42",
  data: {
    sourceWorkspaceID: "ws_staging_07",
    targetWorkspaceID: "ws_prod_42"
  }
});

if (result.imported) {
  console.log("TODO imported into", result.targetWorkspaceID);
}
```

### Response



```json
{
  "imported": true,
  "targetWorkspaceID": "ws_prod_42"
}
```


```json
{
  "data": {},
  "errors": [
    {
      "propertyNames": ["sourceWorkspaceID"],
      "message": "sourceWorkspaceID must be a non-empty string"
    }
  ],
  "success": false
}
```