> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nymblecommerce.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Company Docs API Reference for Nymble Commerce

> REST API reference for Nymble Commerce Company Docs — manage folders, upload documents, generate signed CDN URLs, and monitor storage usage.

The Company Docs API provides your organization with a secure document repository — files are organized in folder hierarchies, stored in cloud object storage, and delivered via time-limited signed CDN URLs. All endpoints require a valid JWT containing an `OrganizationId` claim; your data is always isolated to your own organization.

**Base URL:** `https://api.achievemomentum.com/api/companydocs`

<Note>
  Document CDN URLs expire after **1 hour**. If a URL was generated more than an hour ago, call [refresh-url](#post-apicompanydocsdocumentsdocumentidrefresh-url) before presenting the link to your users.
</Note>

***

## Authentication

All endpoints require a valid JWT in the `Authorization` header:

```http theme={null}
Authorization: Bearer {your-jwt-token}
```

***

## Folders

### POST /api/companydocs/folders

Creates a new folder in your organization's document hierarchy. Folders can be nested by supplying a `parentId`.

#### Request body

<ParamField body="name" type="string" required>
  Folder name. Maximum 255 characters. Cannot contain `/` or `\`.
</ParamField>

<ParamField body="parentId" type="string">
  Parent folder ID. Omit or pass `null` to create the folder at the root level.
</ParamField>

#### Response

<ResponseField name="folder" type="object">
  The created folder.

  <Expandable title="Folder object" />
</ResponseField>

```json title="Example request" theme={null}
{
  "name": "HR Documents",
  "parentId": null
}
```

```json title="Example response" theme={null}
{
  "folder": {
    "folderId": "folder_abc123",
    "organizationId": "org_xyz789",
    "name": "HR Documents",
    "parentId": null,
    "path": "/HR Documents",
    "externalId": null,
    "createdAt": "2024-01-15T10:00:00Z",
    "updatedAt": "2024-01-15T10:00:00Z"
  }
}
```

```bash title="curl example" theme={null}
curl -X POST \
  "https://api.achievemomentum.com/api/companydocs/folders" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "HR Documents", "parentId": null }'
```

***

### GET /api/companydocs/folders

Returns all folders in your organization's document hierarchy.

#### Response

<ResponseField name="folders" type="array">
  Array of folder objects.

  <Expandable title="Folder object" />
</ResponseField>

```bash title="curl example" theme={null}
curl -X GET \
  "https://api.achievemomentum.com/api/companydocs/folders" \
  -H "Authorization: Bearer <your_token>"
```

***

### GET /api/companydocs/folders/{folderId}

Returns a specific folder by its ID.

#### Path parameters

<ParamField path="folderId" type="string" required>
  The folder's unique identifier.
</ParamField>

#### Response

<ResponseField name="folder" type="object">
  The requested folder object. Shape is identical to the [create folder response](#post-apicompanydocsfolders).
</ResponseField>

```bash title="curl example" theme={null}
curl -X GET \
  "https://api.achievemomentum.com/api/companydocs/folders/folder_abc123" \
  -H "Authorization: Bearer <your_token>"
```

***

### DELETE /api/companydocs/folders/{folderId}

Permanently deletes a folder. The folder must be empty — it cannot contain any documents or subfolders.

<Warning>
  You must move or delete all documents and subfolders before deleting the parent folder. A `400` error is returned if the folder is not empty.
</Warning>

#### Path parameters

<ParamField path="folderId" type="string" required>
  The folder's unique identifier.
</ParamField>

#### Response

Returns `204 No Content` on success.

| Status | Description                  |
| ------ | ---------------------------- |
| `204`  | Folder deleted successfully. |
| `400`  | Folder is not empty.         |
| `404`  | Folder not found.            |

```bash title="curl example" theme={null}
curl -X DELETE \
  "https://api.achievemomentum.com/api/companydocs/folders/folder_abc123" \
  -H "Authorization: Bearer <your_token>"
```

***

## Documents

### POST /api/companydocs/documents/upload

Uploads a document to your organization's storage. Send the request as `multipart/form-data`. The response includes a signed CDN URL valid for 1 hour.

<Tip>
  The maximum file size is **50 MB**. Check file size client-side before uploading to provide a better user experience.
</Tip>

#### Request (multipart/form-data)

<ParamField body="file" type="file" required>
  The file to upload.
</ParamField>

<ParamField body="folderId" type="string">
  Target folder ID. Omit to upload to the root level.
</ParamField>

#### Response

<ResponseField name="document" type="object">
  The uploaded document record.

  <Expandable title="Document object" />
</ResponseField>

```bash title="curl example" theme={null}
curl -X POST \
  "https://api.achievemomentum.com/api/companydocs/documents/upload" \
  -H "Authorization: Bearer <your_token>" \
  -F "file=@/path/to/document.pdf" \
  -F "folderId=folder_abc123"
```

```json title="Example response" theme={null}
{
  "document": {
    "documentId": "doc_xyz789",
    "organizationId": "org_xyz789",
    "name": "document.pdf",
    "fileExtension": ".pdf",
    "mimeType": "application/pdf",
    "size": 204800,
    "folderId": "folder_abc123",
    "cdnUrl": "https://cdn.achievemomentum.com/signed/doc_xyz789?token=...",
    "path": "/HR Documents/document.pdf",
    "externalId": null,
    "createdAt": "2024-01-15T11:00:00Z",
    "updatedAt": "2024-01-15T11:00:00Z"
  }
}
```

***

### GET /api/companydocs/documents

Returns all documents in your organization, optionally filtered to a specific folder.

#### Query parameters

<ParamField query="folderId" type="string">
  Filter documents by folder ID. Omit to list all documents across all folders.
</ParamField>

#### Response

<ResponseField name="documents" type="array">
  Array of document objects. Shape is identical to the [upload response document object](#post-apicompanydocsdocumentsupload).
</ResponseField>

```bash title="curl example — all documents" theme={null}
curl -X GET \
  "https://api.achievemomentum.com/api/companydocs/documents" \
  -H "Authorization: Bearer <your_token>"
```

```bash title="curl example — documents in a folder" theme={null}
curl -X GET \
  "https://api.achievemomentum.com/api/companydocs/documents?folderId=folder_abc123" \
  -H "Authorization: Bearer <your_token>"
```

***

### GET /api/companydocs/documents/{documentId}

Returns metadata for a specific document by its ID. Includes a signed CDN URL valid for 1 hour.

#### Path parameters

<ParamField path="documentId" type="string" required>
  The document's unique identifier.
</ParamField>

#### Response

<ResponseField name="document" type="object">
  The document metadata object. Shape is identical to the [upload response document object](#post-apicompanydocsdocumentsupload).
</ResponseField>

```bash title="curl example" theme={null}
curl -X GET \
  "https://api.achievemomentum.com/api/companydocs/documents/doc_xyz789" \
  -H "Authorization: Bearer <your_token>"
```

***

### GET /api/companydocs/documents/{documentId}/download

Downloads the raw file content for a specific document. Returns a binary stream with appropriate `Content-Type` and `Content-Disposition` headers.

#### Path parameters

<ParamField path="documentId" type="string" required>
  The document's unique identifier.
</ParamField>

#### Response

Returns a binary file stream.

| Header                | Value                                       |
| --------------------- | ------------------------------------------- |
| `Content-Type`        | Document MIME type (e.g. `application/pdf`) |
| `Content-Disposition` | `attachment; filename="document.pdf"`       |
| `Content-Length`      | File size in bytes                          |

```bash title="curl example" theme={null}
curl -X GET \
  "https://api.achievemomentum.com/api/companydocs/documents/doc_xyz789/download" \
  -H "Authorization: Bearer <your_token>" \
  --output document.pdf
```

***

### PUT /api/companydocs/documents/{documentId}/move

Moves a document to a different folder. Pass `null` as `targetFolderId` to move the document to the root level.

#### Path parameters

<ParamField path="documentId" type="string" required>
  The document's unique identifier.
</ParamField>

#### Request body

<ParamField body="targetFolderId" type="string | null" required>
  The ID of the destination folder, or `null` to move to the root level.
</ParamField>

#### Response

Returns `204 No Content` on success.

| Status | Description                          |
| ------ | ------------------------------------ |
| `204`  | Document moved successfully.         |
| `400`  | Invalid operation.                   |
| `404`  | Document or target folder not found. |

```bash title="curl example" theme={null}
curl -X PUT \
  "https://api.achievemomentum.com/api/companydocs/documents/doc_xyz789/move" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{ "targetFolderId": "folder_def456" }'
```

***

### DELETE /api/companydocs/documents/{documentId}

Permanently deletes a document and removes its file from cloud storage.

<Warning>
  This action permanently deletes the file and cannot be undone.
</Warning>

#### Path parameters

<ParamField path="documentId" type="string" required>
  The document's unique identifier.
</ParamField>

#### Response

Returns `204 No Content` on success.

```bash title="curl example" theme={null}
curl -X DELETE \
  "https://api.achievemomentum.com/api/companydocs/documents/doc_xyz789" \
  -H "Authorization: Bearer <your_token>"
```

***

### POST /api/companydocs/documents/bulk-delete

Deletes up to 100 documents in a single request.

#### Request body

<ParamField body="documentIds" type="string[]" required>
  Array of document IDs to delete. Maximum 100 IDs per request.
</ParamField>

#### Response

Returns `204 No Content` on success.

| Status | Description                                                            |
| ------ | ---------------------------------------------------------------------- |
| `204`  | All specified documents deleted.                                       |
| `400`  | Validation error (e.g. more than 100 IDs supplied, or an empty array). |

```bash title="curl example" theme={null}
curl -X POST \
  "https://api.achievemomentum.com/api/companydocs/documents/bulk-delete" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "documentIds": ["doc_001", "doc_002", "doc_003"]
  }'
```

***

### POST /api/companydocs/documents/bulk-move

Moves up to 100 documents to a target folder in a single request. Pass `null` as `targetFolderId` to move documents to the root level.

#### Request body

<ParamField body="documentIds" type="string[]" required>
  Array of document IDs to move. Maximum 100 IDs per request.
</ParamField>

<ParamField body="targetFolderId" type="string | null" required>
  The ID of the destination folder, or `null` to move documents to the root level.
</ParamField>

#### Response

Returns `204 No Content` on success.

| Status | Description                                                            |
| ------ | ---------------------------------------------------------------------- |
| `204`  | All specified documents moved.                                         |
| `400`  | Validation error (e.g. more than 100 IDs, or target folder not found). |

```bash title="curl example" theme={null}
curl -X POST \
  "https://api.achievemomentum.com/api/companydocs/documents/bulk-move" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "documentIds": ["doc_001", "doc_002", "doc_003"],
    "targetFolderId": "folder_def456"
  }'
```

***

### POST /api/companydocs/documents/{documentId}/refresh-url

Generates a new signed CDN URL for a document. Use this endpoint when an existing URL has expired (CDN URLs expire after 1 hour) or is about to expire.

#### Path parameters

<ParamField path="documentId" type="string" required>
  The document's unique identifier.
</ParamField>

#### Response

<ResponseField name="cdnUrl" type="string">
  A new signed CDN URL, valid for 1 hour from the time of this request.
</ResponseField>

```json title="Example response" theme={null}
{
  "cdnUrl": "https://cdn.achievemomentum.com/signed/doc_xyz789?token=new_signed_token..."
}
```

```bash title="curl example" theme={null}
curl -X POST \
  "https://api.achievemomentum.com/api/companydocs/documents/doc_xyz789/refresh-url" \
  -H "Authorization: Bearer <your_token>"
```

***

## Statistics

### GET /api/companydocs/stats/storage

Returns storage usage statistics for your organization.

#### Response

<ResponseField name="stats" type="object">
  Storage usage summary.

  <Expandable title="StorageStats object">
    <ResponseField name="totalFiles" type="integer">
      Total number of documents stored.
    </ResponseField>

    <ResponseField name="totalSize" type="integer">
      Total storage used, in bytes.
    </ResponseField>

    <ResponseField name="maxSize" type="integer">
      Maximum allowed storage, in bytes.
    </ResponseField>

    <ResponseField name="usedPercentage" type="number">
      Percentage of your storage quota currently in use (0–100).
    </ResponseField>

    <ResponseField name="availableSize" type="integer">
      Remaining available storage, in bytes.
    </ResponseField>
  </Expandable>
</ResponseField>

```json title="Example response" theme={null}
{
  "stats": {
    "totalFiles": 1247,
    "totalSize": 5368709120,
    "maxSize": 10737418240,
    "usedPercentage": 50.0,
    "availableSize": 5368709120
  }
}
```

```bash title="curl example" theme={null}
curl -X GET \
  "https://api.achievemomentum.com/api/companydocs/stats/storage" \
  -H "Authorization: Bearer <your_token>"
```

***

## Error responses

All endpoints return standard error shapes:

```json title="400 — Validation error" theme={null}
{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred",
  "status": 400,
  "errors": {
    "Name": ["Folder name is required"],
    "DocumentIds": ["Cannot delete more than 100 documents at once"]
  }
}
```

```json title="404 — Not found" theme={null}
{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
  "title": "Not Found",
  "status": 404
}
```

```json title="500 — Server error" theme={null}
{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.6.1",
  "title": "An error occurred while processing your request",
  "status": 500
}
```