# `GET /v1/workspace/status` — Get the working copies' status

Part of the [Bkper Managed Agent API](https://bkper.com/docs/api/managed-agent.md). Read its guide for authentication, conventions, and examples.

Each working copy in the sandbox with its fingerprint, base and marks, and every App folder there, also those Bkper does not know yet: one call to tell what changed. Starts the sandbox when it sleeps; never fetches.

## Operation contract

```json
{
  "operationId": "getWorkspaceStatus",
  "tags": [
    "Workspace"
  ],
  "summary": "Get the working copies' status",
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "parameters": [],
  "description": "Each working copy in the sandbox with its fingerprint, base and marks, and every App folder there, also those Bkper does not know yet: one call to tell what changed. Starts the sandbox when it sleeps; never fetches.",
  "responses": {
    "200": {
      "description": "Success",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/WorkspaceStatus"
          }
        }
      }
    },
    "400": {
      "description": "Rejected; never contains credentials or upstream payloads.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "Rejected; never contains credentials or upstream payloads.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Rejected; never contains credentials or upstream payloads.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "Rejected; never contains credentials or upstream payloads.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "409": {
      "description": "Rejected; never contains credentials or upstream payloads.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "410": {
      "description": "Rejected; never contains credentials or upstream payloads.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "411": {
      "description": "Rejected; never contains credentials or upstream payloads.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "413": {
      "description": "Rejected; never contains credentials or upstream payloads.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "422": {
      "description": "Rejected; never contains credentials or upstream payloads.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "503": {
      "description": "Rejected; never contains credentials or upstream payloads.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}
```

## Schemas

### WorkspaceStatus

```json
{
  "type": "object",
  "properties": {
    "repositories": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "repository": {
            "type": "string",
            "description": "Which: user, domain, books/{bookId} or apps/{appId}."
          },
          "fingerprint": {
            "type": "string",
            "pattern": "^[0-9a-f]{40,64}$",
            "description": "Git's tree id of the working copy, untracked files included, ignored ones left out: it changes whenever its files do, so an unchanged one needs nothing read again. Save takes the review's."
          },
          "base": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "The published commit the working copy builds on (where its commits and what is published meet), so a newer publish by someone else marks nothing; null while nothing was published."
          },
          "marks": {
            "type": "object",
            "properties": {
              "added": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Files the base does not have."
              },
              "modified": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Files that differ from the base."
              },
              "deleted": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Files of the base no longer there."
              }
            },
            "required": [
              "added",
              "modified",
              "deleted"
            ],
            "description": "The files that differ from the base, committed or not, by path: what Save would publish."
          },
          "folder": {
            "description": "An App's: its folder in the sandbox, /workspace/apps/{folder}.",
            "type": "string"
          },
          "name": {
            "description": "An App's: the name in its bkper.yaml.",
            "type": "string"
          }
        },
        "required": [
          "repository",
          "fingerprint",
          "base",
          "marks"
        ]
      },
      "description": "Each working copy the sandbox has, by `repository`: context the agent cloned or the user opened, and every App folder in /workspace/apps by its bkper.yaml `id` (one per App). An App not among the root's `apps` is not known to Bkper yet: it cannot be saved (409 app_unregistered) until the agent registers it."
    }
  },
  "required": [
    "repositories"
  ],
  "description": "The working copies of the workspace's sandbox, read from the sandbox alone: never fetched."
}
```

### Error

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "Stable code, e.g. not_found, idempotency_conflict, session_working, usage_limit_exceeded. Open."
        },
        "type": {
          "description": "Category, e.g. invalid_request_error, authentication_error, usage_limit_error. Open.",
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "host": {
          "description": "host_in_use: the host another service holds.",
          "type": "string"
        },
        "service": {
          "description": "host_in_use: the id of the service that holds the host.",
          "type": "string"
        },
        "reason": {
          "description": "file_invalid: why the change, or a picture, was refused. Open: path | text | size | skill | skills | count | type.",
          "type": "string"
        },
        "paths": {
          "description": "file_exists from an add: every path of the request where a file is and `replace` was not set, all at once, so the person can be asked once. publish_conflict: the files someone published changes to the same lines of.",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "publishers": {
          "description": "publish_conflict: who published those changes, by name.",
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "code"
      ]
    }
  },
  "required": [
    "error"
  ]
}
```

## Authentication

```json
{
  "bearerAuth": {
    "type": "http",
    "scheme": "bearer"
  }
}
```