# Update document template

Rename a document template or change its workspace sharing. Editing requires the template’s owner, creator or a workspace administrator.

POST https://api.brigg.app/v1/operations/documents.UpdateDocumentTemplate

## Access & visibility

Allow `documents.UpdateDocumentTemplate` on your API key.

**Acting member required.** Send `Brigg-Act-As` with an [approved member account ID](https://developer.brigg.app/authentication#member-delegation). The key supplies permissions; the member selects whose data is used.

The selected member must be active and approved by the credential. This selects whose private data is used; the credential supplies permissions. Private ownership and project boundaries still apply.

[Set up authentication](https://developer.brigg.app/authentication) · [Choose permissions](https://developer.brigg.app/permissions)

## Request fields

Send a JSON object with the following fields. Required fields must be included; omit optional fields you do not need.
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `template_id` | string | Yes | Use a template_id from the template catalogue; this is not the ID of a generated document. [workspace.ListTemplates](https://developer.brigg.app/reference/workspace/ListTemplates). At least 1 character. |
| `label` | string | No | New display name for the template. Omit to preserve the name; this does not edit its document content or fields. At least 1 character. At most 200 characters. |
| `level` | string | No | org shares with the workspace; user returns it to its original creator when that person is still a member, otherwise to the acting member. Omit to preserve sharing. Allowed: `"org"`, `"user"`. |

## Rename or share an existing document template

Choose a document template from [List templates](https://developer.brigg.app/reference/workspace/ListTemplates). App templates and newsletter templates are different resources and are not accepted here. A change to level affects future template discovery; it does not rewrite documents already generated from that template.

Making a template private removes it from colleagues’ normal lists, but keeps any existing saved version. It does not retract bytes already downloaded or make earlier copies disappear. Read ListTemplates again to confirm the resulting label and owner_account_id.

## Response

Returns **200 OK** with a JSON body.

The acting member must own the template, have created it, or be a workspace owner or administrator. Being able to read a shared template does not by itself allow changing or deleting it.

Send label, level, or both. Omitting both makes no requested metadata change. This operation does not change template instructions; use the template-field operations for those.
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `ok` | boolean | Yes | The requested metadata changes were saved. |
| `published` | boolean | Yes | True only when this sharing change created an initial saved content version so colleagues can render the template. False for a rename, making it private, or sharing a template that already had a saved version. This is not a current-publication or public-web visibility flag. |

## Errors & retries

Set `BRIGG_REQUEST_ID` once for each logical action. The samples send it as `Idempotency-Key`. Reuse the same value and body on retries, including after a timeout; a missing response does not prove the action failed.

For rate limits, follow the server’s retry guidance and back off. See [HTTP errors](https://developer.brigg.app/http#errors) and [safe retries and limits](https://developer.brigg.app/reliability).

| HTTP status | Code | What to do |
| --- | --- | --- |
| 400 | `invalid_json` | Send a JSON object with Content-Type: application/json. |
| 400 | `invalid_input` | Check the request fields and types. Supply a stable Idempotency-Key containing 1–200 characters. |
| 401 | `invalid_key` | The workspace API key is missing, invalid or revoked. |
| 403 | `forbidden` | The acting member must own the template, have created it, or currently be a workspace owner or administrator. Read access alone is insufficient. |
| 404 | `not_found` | The requested operation or resource is not available to this credential. |
| 429 | `rate_limited` | Wait for Retry-After before retrying. Reuse the original Idempotency-Key. |
| 404 | `template_not_found` | Choose a document template from ListTemplates; app and newsletter templates are not accepted. |

## Next steps

- [List templates](https://developer.brigg.app/reference/workspace/ListTemplates)
- [List document template fields](https://developer.brigg.app/reference/documents/ListDocumentTemplateFields)
- [Delete document template](https://developer.brigg.app/reference/documents/DeleteDocumentTemplate)

[Download OpenAPI](https://developer.brigg.app/openapi.json) · [Versioning & retirement](https://developer.brigg.app/versioning)

## Examples

### Rename without changing access

Omitted level preserves current sharing.
#### cURL


```sh
curl 'https://api.brigg.app/v1/operations/documents.UpdateDocumentTemplate' \
  -H "Authorization: Bearer $BRIGG_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Brigg-Act-As: $BRIGG_ACT_AS" \
  -H "Idempotency-Key: $BRIGG_REQUEST_ID" \
  --data-raw '{
  "template_id": "c_template_proposal",
  "label": "Project proposal"
}'
```

#### TypeScript


```typescript
const actAs = process.env.BRIGG_ACT_AS;
if (!actAs) throw new Error("Set BRIGG_ACT_AS to an approved member account ID.");

const requestId = process.env.BRIGG_REQUEST_ID;
if (!requestId) throw new Error("Set BRIGG_REQUEST_ID once per action and reuse it on retries.");

const response = await fetch("https://api.brigg.app/v1/operations/documents.UpdateDocumentTemplate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BRIGG_API_KEY}`,
    "Content-Type": "application/json",
    "Brigg-Act-As": actAs,
    "Idempotency-Key": requestId, // Create once per action; reuse on retries.
  },
  body: JSON.stringify({
    "template_id": "c_template_proposal",
    "label": "Project proposal"
  }),
});
const result = await response.json();
if (!response.ok) throw new Error(`${response.status}: ${result.error} — ${result.message}`);
console.log(result);
```

#### Python


```python
import json
import os
from urllib.request import Request, urlopen
from urllib.error import HTTPError

request_id = os.environ["BRIGG_REQUEST_ID"]  # Reuse for retries of this action.
payload = {
  "template_id": "c_template_proposal",
  "label": "Project proposal"
}
request = Request(
    "https://api.brigg.app/v1/operations/documents.UpdateDocumentTemplate",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {os.environ['BRIGG_API_KEY']}",
        "Content-Type": "application/json",
        "Brigg-Act-As": os.environ["BRIGG_ACT_AS"],
        "Idempotency-Key": request_id,  # Create once per action; reuse on retries.
    },
    method="POST",
)
try:
    with urlopen(request) as response:
        print(json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))
    raise
```

#### Response example


```json
{
  "ok": true,
  "published": false
}
```

### Share a personal template

This example template has no saved version yet, so sharing creates one.
#### cURL


```sh
curl 'https://api.brigg.app/v1/operations/documents.UpdateDocumentTemplate' \
  -H "Authorization: Bearer $BRIGG_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Brigg-Act-As: $BRIGG_ACT_AS" \
  -H "Idempotency-Key: $BRIGG_REQUEST_ID" \
  --data-raw '{
  "template_id": "c_template_proposal",
  "level": "org"
}'
```

#### TypeScript


```typescript
const actAs = process.env.BRIGG_ACT_AS;
if (!actAs) throw new Error("Set BRIGG_ACT_AS to an approved member account ID.");

const requestId = process.env.BRIGG_REQUEST_ID;
if (!requestId) throw new Error("Set BRIGG_REQUEST_ID once per action and reuse it on retries.");

const response = await fetch("https://api.brigg.app/v1/operations/documents.UpdateDocumentTemplate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BRIGG_API_KEY}`,
    "Content-Type": "application/json",
    "Brigg-Act-As": actAs,
    "Idempotency-Key": requestId, // Create once per action; reuse on retries.
  },
  body: JSON.stringify({
    "template_id": "c_template_proposal",
    "level": "org"
  }),
});
const result = await response.json();
if (!response.ok) throw new Error(`${response.status}: ${result.error} — ${result.message}`);
console.log(result);
```

#### Python


```python
import json
import os
from urllib.request import Request, urlopen
from urllib.error import HTTPError

request_id = os.environ["BRIGG_REQUEST_ID"]  # Reuse for retries of this action.
payload = {
  "template_id": "c_template_proposal",
  "level": "org"
}
request = Request(
    "https://api.brigg.app/v1/operations/documents.UpdateDocumentTemplate",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {os.environ['BRIGG_API_KEY']}",
        "Content-Type": "application/json",
        "Brigg-Act-As": os.environ["BRIGG_ACT_AS"],
        "Idempotency-Key": request_id,  # Create once per action; reuse on retries.
    },
    method="POST",
)
try:
    with urlopen(request) as response:
        print(json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))
    raise
```

#### Response example


```json
{
  "ok": true,
  "published": true
}
```

### Return a template to personal use

The creator still belongs to the workspace. Its existing saved version remains.
#### cURL


```sh
curl 'https://api.brigg.app/v1/operations/documents.UpdateDocumentTemplate' \
  -H "Authorization: Bearer $BRIGG_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Brigg-Act-As: $BRIGG_ACT_AS" \
  -H "Idempotency-Key: $BRIGG_REQUEST_ID" \
  --data-raw '{
  "template_id": "c_template_proposal",
  "level": "user"
}'
```

#### TypeScript


```typescript
const actAs = process.env.BRIGG_ACT_AS;
if (!actAs) throw new Error("Set BRIGG_ACT_AS to an approved member account ID.");

const requestId = process.env.BRIGG_REQUEST_ID;
if (!requestId) throw new Error("Set BRIGG_REQUEST_ID once per action and reuse it on retries.");

const response = await fetch("https://api.brigg.app/v1/operations/documents.UpdateDocumentTemplate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BRIGG_API_KEY}`,
    "Content-Type": "application/json",
    "Brigg-Act-As": actAs,
    "Idempotency-Key": requestId, // Create once per action; reuse on retries.
  },
  body: JSON.stringify({
    "template_id": "c_template_proposal",
    "level": "user"
  }),
});
const result = await response.json();
if (!response.ok) throw new Error(`${response.status}: ${result.error} — ${result.message}`);
console.log(result);
```

#### Python


```python
import json
import os
from urllib.request import Request, urlopen
from urllib.error import HTTPError

request_id = os.environ["BRIGG_REQUEST_ID"]  # Reuse for retries of this action.
payload = {
  "template_id": "c_template_proposal",
  "level": "user"
}
request = Request(
    "https://api.brigg.app/v1/operations/documents.UpdateDocumentTemplate",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {os.environ['BRIGG_API_KEY']}",
        "Content-Type": "application/json",
        "Brigg-Act-As": os.environ["BRIGG_ACT_AS"],
        "Idempotency-Key": request_id,  # Create once per action; reuse on retries.
    },
    method="POST",
)
try:
    with urlopen(request) as response:
        print(json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))
    raise
```

#### Response example


```json
{
  "ok": true,
  "published": false
}
```

## JSON schemas


```json-schema-request
{
  "type": "object",
  "properties": {
    "template_id": {
      "type": "string",
      "minLength": 1,
      "description": "Use a template_id from the template catalogue; this is not the ID of a generated document. [workspace.ListTemplates](https://developer.brigg.app/reference/workspace/ListTemplates)."
    },
    "label": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "New display name for the template. Omit to preserve the name; this does not edit its document content or fields."
    },
    "level": {
      "type": "string",
      "enum": [
        "org",
        "user"
      ],
      "description": "org shares with the workspace; user returns it to its original creator when that person is still a member, otherwise to the acting member. Omit to preserve sharing."
    }
  },
  "required": [
    "template_id"
  ],
  "additionalProperties": false,
  "examples": [
    {
      "template_id": "c_template_proposal",
      "label": "Project proposal"
    }
  ]
}
```


```json-schema-response
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "The requested metadata changes were saved."
    },
    "published": {
      "type": "boolean",
      "description": "True only when this sharing change created an initial saved content version so colleagues can render the template. False for a rename, making it private, or sharing a template that already had a saved version. This is not a current-publication or public-web visibility flag."
    }
  },
  "required": [
    "ok",
    "published"
  ],
  "additionalProperties": false,
  "examples": [
    {
      "ok": true,
      "published": false
    }
  ]
}
```