# Create document metadata

URL: /en/docs/api/v1/documents/post
Last Updated: 2026-07-30T21:15:44.939Z

## Description
No description available.

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

## Content
### POST /api/v1/documents

**Create document metadata**

Create document metadata without file upload. File must be uploaded separately using the file upload endpoint.

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

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

- `title` (string, required): Document title
- `slug` (string): Optional URL-friendly slug for public links
- `description` (string): Document description
- `description_markdown` (string): Markdown-formatted description
- `source` (enum: google_docs | sharepoint | notion): Optional document source/provider
- `source_id` (string): Provider-specific ID for the document
- `category` (string (uuid), required): Category ID (must be UUID)
- `access_level` (enum: public | restricted | requires_nda | internal, required): Document access level
- `issue_date` (string (date)): Issue date in YYYY-MM-DD format
- `expiry_date` (string (date)): Expiry date in YYYY-MM-DD format
- `validity_months` (integer): Validity period in months
- `status` (enum: draft | published | archived): Initial document status
- `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): Show validity period on card display
- `template` (string (uuid)): Template ID to use for document creation
- `variant_options` (array of string (uuid)): Variant option IDs to assign to this item (default locale only).

Example (Basic public document):

```json
{
  "title": "Privacy Policy",
  "description": "Company privacy policy document",
  "category": "550e8400-e29b-41d4-a716-446655440000",
  "access_level": "public"
}
```

Example (Restricted document with expiry):

```json
{
  "title": "SOC 2 Type II Report",
  "description": "Annual security audit report",
  "category": "550e8400-e29b-41d4-a716-446655440000",
  "access_level": "restricted",
  "issue_date": "2025-01-01",
  "validity_months": 12,
  "featured": {
    "control": true,
    "resource": false
  }
}
```

Example (Document requiring NDA):

```json
{
  "title": "Sensitive Infrastructure Details",
  "description": "Technical infrastructure documentation",
  "description_markdown": "## Infrastructure Overview\n\nDetailed technical specifications...",
  "category": "550e8400-e29b-41d4-a716-446655440000",
  "access_level": "requires_nda",
  "status": "published",
  "featured": {
    "control": false,
    "resource": true
  }
}
```

**Responses:**

- `201` - Document metadata created successfully
  - `success` (boolean)
  - `data` (object)
    - `documentId` (string (uuid)): ID of the created document
    - `uploadUrl` (string): URL for file upload
- `400` - Bad Request - validation failed
  - `error` (string): Validation error message
- `401` - Unauthorized
- `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 POST "https://app.orbiqhq.com/api/v1/documents" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Privacy Policy",
  "description": "Company privacy policy document",
  "access_level": "public"
}'
```