Orchestration: Vault & Import

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

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

Response

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

{
  "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

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

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

Response

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

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

{
  "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

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

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

Response

{
  "synced": true
}

{
  "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

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

{
  "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

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

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

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