# Update document metadata

URL: /en/docs/api/v1/documents/id/patch
Last Updated: 2026-07-30T21:15:29.889Z

## Description
No description available.

## Available Actions
- Execute PATCH request
- View request parameters
- View response schema
- Get code examples
- Navigate to related topics
- View step-by-step instructions
- Get best practices

## Content
### PATCH /api/v1/documents/{id}

**Update document metadata**

Update document metadata including title, description, category, access level, and validity information. File updates must be done separately.

**Authentication:** Bearer token (`Authorization: Bearer <token>`)

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string (uuid) | Yes | Document ID |

**Request body** (`application/json`) - required:

- `title` (string): Document title
- `slug` (string): Optional URL-friendly slug for public links
- `description` (string): Document description
- `description_markdown` (string): Markdown-formatted description
- `access_level` (enum: public | restricted | requires_nda | internal): Document access level
- `issue_date` (string (date)): Issue date in YYYY-MM-DD format (empty string treated as null)
- `expiry_date` (string (date)): Expiry date in YYYY-MM-DD format (empty string treated as null)
- `validity_months` (integer): Validity period in months
- `featured` (object): Featured placement flags for controls/resources sections
  - `control` (boolean): Feature this document in the Controls overview panels
  - `resource` (boolean): Feature this document in the Trust Center Resources panel
- `category` (string (uuid)): Category ID to assign document to
- `variant_options` (array of string): Variant option IDs to assign this document to. Replaces all existing assignments. Only accepted on default-locale updates; supplying it on a non-default-locale (translation) update returns 400 with error `variant_options_default_locale_only`. Unknown or foreign option IDs return 400 with error `unknown_variant_options`. Option ownership is validated before any write; assignments are applied after the content update succeeds. If the content update succeeds but the assignment sync fails, the response is still 200 and includes `variant_assignments_warning: variant_assignments_failed` while omitting `variant_options`; an assignment-only update that fails to sync returns 500 with error `variant_assignments_failed`. On success the response echoes the assigned option IDs as `variant_options`.

Example (Update title and description):

```json
{
  "title": "Updated Privacy Policy",
  "description": "Revised company privacy policy for 2025"
}
```

Example (Clear the slug):

```json
{
  "slug": null
}
```

Example (Change access level to restricted):

```json
{
  "access_level": "restricted",
  "featured": {
    "control": true,
    "resource": false
  }
}
```

Example (Update validity period):

```json
{
  "issue_date": "2025-01-15",
  "validity_months": 24
}
```

Example (Complete document update):

```json
{
  "title": "SOC 2 Type II Report - 2025",
  "description": "Annual security compliance audit report",
  "description_markdown": "## SOC 2 Compliance\n\nFull audit results...",
  "category": "550e8400-e29b-41d4-a716-446655440000",
  "access_level": "restricted",
  "issue_date": "2025-01-01",
  "validity_months": 12,
  "featured": {
    "control": true,
    "resource": true
  }
}
```

**Responses:**

- `200` - Document updated successfully
  - `success` (boolean)
  - `data` (DocumentDetailed (object))
    - `id` (string (uuid)): Unique document identifier
    - `title` (string): Document title
    - `slug` (string): Optional URL-friendly slug for public links
    - `description` (string): Document description
    - `description_markdown` (string): Markdown-formatted description
    - `category` (Category (object))
      - `id` (string (uuid)): Category identifier
      - `title` (string): Localized category name
      - `icon` (string): Optional icon identifier for the category
      - `translations` (array of CategoryTranslation (object)): Available localized labels for the category
        - `locale` (string, required): Normalized locale/language code (e.g., de, fr)
        - `title` (string, required): Localized category title
        - `description` (string): Localized category description if provided
    - `access_level` (enum: public | restricted | requires_nda | internal): Document access level
    - `status` (enum: draft | published | archived): Document status (only available when versioning is disabled)
    - `issue_date` (string (date)): Document issue date in YYYY-MM-DD format
    - `expiry_date` (string (date)): Document expiry date in YYYY-MM-DD format
    - `validity_months` (integer): Document validity period in months
    - `featured` (object): Featured placement flags for controls/resources sections
      - `control` (boolean): Feature this document in the Controls overview panels
      - `resource` (boolean): Feature this document in the Trust Center Resources panel
    - `show_validity_period_on_card` (boolean): Whether to show validity period on card display
    - `file` (object)
      - `id` (string (uuid)): File identifier
      - `filename_download` (string): Original filename for download
      - `filesize` (integer): File size in bytes
      - `type` (string): MIME type of the file
      - `title` (string): File title
      - `url` (string (uri)): URL to access the file with access token
    - `date_created` (string (date-time)): Document creation timestamp
    - `date_updated` (string (date-time)): Last update timestamp
    - `versioning` (boolean): Indicates whether content versioning is enabled for this document
    - `_version` (object): Metadata about the currently merged version when viewing a draft
      - `id` (string): Version identifier
      - `key` (string): Internal Directus key for the version
      - `name` (string): Human-readable version name
      - `status` (enum: draft | published | archived)
      - `is_active` (boolean)
      - `date_created` (string (date-time))
      - `date_updated` (string (date-time))
    - `publishedVersions` (array of DocumentVersionSummary (object)): Summary of available published versions (latest first)
      - `id` (string): Version identifier
      - `name` (string)
      - `status` (enum: draft | published | archived)
      - `is_active` (boolean)
      - `date_created` (string (date-time))
      - `date_updated` (string (date-time))
    - `activeVersionId` (string): Identifier of the active (promoted) version when versioning is enabled
    - `defaultVersionId` (string): Identifier of the default version used for public display
    - `defaultVersionName` (string): Display name of the default version
- `400` - Bad Request - validation failed or no changes submitted
  - `error` (object)
    - `type` (string)
    - `code` (string)
    - `message` (string)
- `401` - Unauthorized
- `404` - Document not found
- `409` - Conflict - slug already exists
  - `error` (string, required)
  - `fieldErrors` (object, required)
    - `slug` (array of string)
  - `duplicateSlugResource` (object, required)
    - `id` (string, required): Conflicting document or certification ID
    - `title` (string, required): Conflicting resource title
    - `type` (enum: document | certification, required)
    - `href` (string, required): Admin Center path for the conflicting resource
- `500` - Internal server error

**Code samples:**

cURL:

```bash
curl -X PATCH "https://app.orbiqhq.com/api/v1/documents/{id}" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json"
```