> Documentation index: [/llms.txt](/llms.txt). Every page as one file: [/llms-full.txt](/llms-full.txt).

# Workspace context and templates

Workspace context and templates [#workspace-context-and-templates]

A workspace's context is its mission and goals; its templates are `.docx` and `.pptx` files. An agent with `use_ontology` gets the context in its prompt, and one with `use_templates` can use the templates ([agent fields](../configurable-agents/create-and-configure#agentyaml-keys)).

Endpoints [#endpoints]

Every route needs `X-Space-Slug`. Changes need the workspace `admin` role; other members get `403`.

| Method        | URL                                                                 | Does                                                                                  | Auth          |
| ------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------- |
| `GET` · `PUT` | `/api/v1/ontology/workspace/`                                       | Read · replace `workspace_mission` and `workspace_goals`                              | Key or bearer |
| `GET`         | `/api/v1/ontology/templates/?search=`                               | Templates by scope: `{workspace: [...], company: [...]}`; `search` matches file names | Key or bearer |
| `POST`        | `/api/v1/ontology/workspace/templates/upload/`                      | Upload one file as `file` (multipart); `.docx` or `.pptx` only                        | Key or bearer |
| `GET`         | `/api/v1/ontology/workspace/templates/{template_id}/presigned-url/` | A short-lived download `url`                                                          | Key or bearer |
| `PATCH`       | `/api/v1/ontology/workspace/templates/{template_id}/`               | Rename: `{name}`                                                                      | Key or bearer |
| `DELETE`      | `/api/v1/ontology/workspace/templates/{template_id}/`               | Delete the template and its file; `204`                                               | Key or bearer |

Company context and company templates (`/api/v1/ontology/company/…`) apply to every workspace and need a signed-in platform admin.

Set the mission and goals [#set-the-mission-and-goals]

```bash
curl -X PUT "$CENTRAL_HUB_URL/api/v1/ontology/workspace/" \
  -H "X-API-Key: $ALO_API_KEY" \
  -H "X-Space-Slug: $WORKSPACE_SLUG" \
  -H "Content-Type: application/json" \
  -d '{"workspace_mission": "Help procurement review supplier contracts", "workspace_goals": [{"title": "Cut review time"}]}'
```

```json
{"id": 1, "space_slug": "acme", "workspace_mission": "Help procurement review supplier contracts", "workspace_goals": [{"title": "Cut review time", "description": null}], "templates": []}
```

Each goal is `{title, description?}`. A field you leave out keeps its value.

Upload a template [#upload-a-template]

```bash
curl -X POST "$CENTRAL_HUB_URL/api/v1/ontology/workspace/templates/upload/" \
  -H "X-API-Key: $ALO_API_KEY" \
  -H "X-Space-Slug: $WORKSPACE_SLUG" \
  -F "file=@contract-template.docx"
```

The response has the template's `id`, `name`, `file_type`, `mime_type`, `size` and a `presigned_url` to download it.

Errors [#errors]

| Response                                                               | Cause                               |
| ---------------------------------------------------------------------- | ----------------------------------- |
| `403` `Only workspace administrators can modify workspace ontology.`   | The caller is not a workspace admin |
| `403` `Only workspace administrators can manage workspace templates.`  | Same, on a template route           |
| `422` `Only .pptx and .docx files are accepted as ontology templates.` | Another file type                   |