# Creates a document.

POST https://api.awork.com/api/v1/documents

Creates a document with optional HTML or Markdown content. Set `contentFormat` to `html` or `markdown`; HTML is the default. Exported Markdown uses hidden metadata to preserve safe editor structures during re-import.

<Check title="Required Permissions" icon="key">Any authenticated user.</Check>

## Request example

```sh
curl -X POST --globoff 'https://api.awork.com/api/v1/documents' \
  -H 'Authorization: Bearer <token>' \
  -F 'name=string' \
  -F 'documentSpaceId=123e4567-e89b-12d3-a456-426614174000' \
  -F 'parentId=123e4567-e89b-12d3-a456-426614174000' \
  -F 'projectId=123e4567-e89b-12d3-a456-426614174000' \
  -F 'taskId=123e4567-e89b-12d3-a456-426614174000' \
  -F 'emoji=string' \
  -F 'isPrivate=true' \
  -F 'order=1' \
  -F 'workspaceAccessLevel=none' \
  -F 'isHiddenForConnectUsers=true' \
  -F 'content=@/path/to/file' \
  -F 'contentFormat=html'
```

## Request body (multipart/form-data)

- `name`: string or null

- `documentSpaceId`: string or null

- `parentId`: string or null

- `projectId`: string or null

- `taskId`: string or null

- `emoji`: string or null

- `isPrivate`: boolean

- `order`: number or null

- `workspaceAccessLevel`: string or null

- `isHiddenForConnectUsers`: boolean or null

- `content`: string or null

- `contentFormat`: string or null

## Response 200

OK

application/json

```json
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "createdOn": "2022-03-11T15:33:47.100Z",
  "createdBy": "123e4567-e89b-12d3-a456-426614174000",
  "updatedOn": "2022-03-11T21:15:00.100Z",
  "updatedBy": "123e4567-e89b-12d3-a456-426614174000",
  "name": "string",
  "currentDocumentVersionId": "123e4567-e89b-12d3-a456-426614174000",
  "documentSpaceId": "123e4567-e89b-12d3-a456-426614174000",
  "documentSpace": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "createdOn": "2022-03-11T15:33:47.100Z",
    "createdBy": "123e4567-e89b-12d3-a456-426614174000",
    "updatedOn": "2022-03-11T21:15:00.100Z",
    "updatedBy": "123e4567-e89b-12d3-a456-426614174000",
    "name": "string",
    "isExternal": true,
    "emoji": "string",
    "color": "purple",
    "order": 1,
    "workspaceAccessLevel": "string",
    "contributors": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "userId": "123e4567-e89b-12d3-a456-426614174000",
        "accessLevel": "string",
        "firstName": "Lisa",
        "lastName": "Smith",
        "hasImage": true,
        "isDeactivated": false
      }
    ],
    "teams": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "teamId": "123e4567-e89b-12d3-a456-426614174000",
        "accessLevel": "string",
        "name": "Designers",
        "icon": "paintbrush",
        "color": "purple"
      }
    ]
  },
  "parentId": "123e4567-e89b-12d3-a456-426614174000",
  "projectId": "123e4567-e89b-12d3-a456-426614174000",
  "project": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "string",
    "createdBy": "123e4567-e89b-12d3-a456-426614174000",
    "teams": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "string"
      }
    ],
    "members": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "projectRoleId": "123e4567-e89b-12d3-a456-426614174000",
        "userId": "123e4567-e89b-12d3-a456-426614174000"
      }
    ],
    "isPrivate": true,
    "isExternal": true
  },
  "taskId": "123e4567-e89b-12d3-a456-426614174000",
  "emoji": "string",
  "isPrivate": true,
  "order": 1,
  "isExternal": true,
  "isHiddenForConnectUsers": true,
  "contributors": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "userId": "123e4567-e89b-12d3-a456-426614174000",
      "accessLevel": "string",
      "firstName": "Lisa",
      "lastName": "Smith",
      "hasImage": true,
      "isDeactivated": false,
      "documentId": "123e4567-e89b-12d3-a456-426614174000",
      "inheritedFromDocumentContributorId": "123e4567-e89b-12d3-a456-426614174000",
      "inheritedDocumentContributor": {
        "documentId": "123e4567-e89b-12d3-a456-426614174000",
        "accessLevel": "string"
      }
    }
  ],
  "teams": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "teamId": "123e4567-e89b-12d3-a456-426614174000",
      "accessLevel": "string",
      "name": "Designers",
      "icon": "paintbrush",
      "color": "purple",
      "documentId": "123e4567-e89b-12d3-a456-426614174000",
      "inheritedFromDocumentToTeamId": "123e4567-e89b-12d3-a456-426614174000",
      "inheritedDocumentToTeam": {
        "documentId": "123e4567-e89b-12d3-a456-426614174000",
        "accessLevel": "string"
      }
    }
  ],
  "workspaceAccessLevel": "string",
  "inheritedWorkspaceAccessFromDocumentId": "123e4567-e89b-12d3-a456-426614174000",
  "inheritedWorkspaceAccessFromDocument": {
    "workspaceAccessLevel": "string"
  },
  "movedToTrashOn": "2026-01-15T09:30:00Z",
  "movedToTrashBy": "123e4567-e89b-12d3-a456-426614174000",
  "rootDocumentCreatedBy": "123e4567-e89b-12d3-a456-426614174000"
}
```