# Document Management API

Use the Document Management REST API lets you upload documents to your organization's brand kit. You can also retrieve documents or delete them when needed. 

 This REST API lets you interect with:

 - The document object. A [brand document](https://doc.sitecore.com/stream/en/users/sitecore-stream/guidelines-for-uploading-brand-documents.html) serves as a source material for your organization's brand. These can include brand guidelines, tone of voice, or messaging frameworks. 

 After uploading documents, you can use the [Pipeline REST API](https://api-docs.sitecore.com/ai-capabilities/ai-pipeline-rest-api) to initiate the [brand ingestion](https://doc.sitecore.com/stream/en/users/sitecore-stream/brand-knowledge.html) process. This enables Sitecore to analyze the uploaded documents, create a database of brand knowledge, and populate the brand kit's sections with relevant content.

Note the following:

 - To use this REST API, you must authenticate your API requests.

 - All API requests are made in your production environment.

For more information, see the [official Sitecore Stream documentation](https://doc.sitecore.com/stream/en/users/sitecore-stream/sitecore-stream.html).

# Authorization
The Document Management REST API uses the OAuth 2.0 standard with [JSON web tokens](https://doc.sitecore.com/stream/en/users/sitecore-stream/generate-a-json-web-token--jwt-.html) to authorize REST API requests.
### Create Client ID and Client Secret
  1. In the Sitecore Cloud Portal, open Stream.
  2. Click **Admin** > **Brand Kit keys** > **Create credential**.
  3. In the **​Create New Client​​** dialog, enter a name and description for the client. Then click **Create**. The ​Client ID and Client Secret​​ display.
  4. Copy the Client ID and Client Secret because you won't be able to view them again in Stream. You'll use them to request an access token.

### Request an access token
Run the following cURL command to request an access token. Replace the placeholder values with your Client ID and Client Secret.
```curl
  curl -X POST 'https://auth.sitecorecloud.io/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id={YOUR_API_KEY}' \
  --data-urlencode 'client_secret={YOUR_API_SECRET}' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'audience=https://api.sitecorecloud.io'
```
In the response, the `access_token` key contains the access token:
```json
  {
    "access_token": "{YOUR_ACCESS_TOKEN}",
    "scope": "ai.org.brd:w ai.org.brd:r ai.org.docs:w ai.org.docs:r ai.org:admin",
    "expires_in": 86400,
    "token_type": "Bearer"
  }
```
Access tokens expire in 24 hours. If your requests unexpectedly return a response with status `401 Unauthorized`, request a new access token by repeating this `POST` request.

We recommend that you cache the access token for 24 hours to avoid repeating this `POST` request while the access token is still valid.
### Include the access token in the request header
You can now start making REST API requests. You must include the access token in the request header of every request. For example:

  ```curl
  curl -X GET '{YOUR_BASE_URL}/v2/...' \
  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}' \
  -H 'Accept: application/json'
  ```


Version: 0.1.0
License: Apache 2.0
Metadata:
  - product: AI capabilities

## Servers

Production server West Europe
```
https://ai-documents-api-euw.sitecorecloud.io
```

Production server East US
```
https://ai-documents-api-use.sitecorecloud.io
```

Production server East Australia
```
https://ai-documents-api-aue.sitecorecloud.io
```

Production server East Japan
```
https://ai-documents-api-jpe.sitecorecloud.io
```

## Security

### HTTPBearer

Type: http
Scheme: bearer
Bearer Format: JWT

## Download OpenAPI description

[Document Management API](https://api-docs.sitecore.com/_spec/ai-capabilities/ai-document-management-rest-api/index.yaml)

## Document

The Docoument API lets you upload, retrieve, or delete [brand documents](https://doc.sitecore.com/stream/en/users/sitecore-stream/guidelines-for-uploading-brand-documents.html) in a brand kit.

### Create a document

 - [POST /api/documents/v2/organizations/{organizationId}/documents](https://api-docs.sitecore.com/ai-capabilities/ai-document-management-rest-api/document/create_document_v2_api_documents_v2_organizations__organizationid__documents_post.md): Uploads a new brand document and uses it as a source of brand information in the specified brand kit.

### List documents

 - [GET /api/documents/v2/organizations/{organizationId}/documents](https://api-docs.sitecore.com/ai-capabilities/ai-document-management-rest-api/document/list_documents_v2_api_documents_v2_organizations__organizationid__documents_get.md): Retrieves a list of documents in an organization. You can filter the results by various parameters, such as brand kit ID, status, type, and tags. This endpoint supports pagination and search functionality.

### Delete a document

 - [DELETE /api/documents/v1/organizations/{organizationId}/documents/{documentId}](https://api-docs.sitecore.com/ai-capabilities/ai-document-management-rest-api/document/delete_document_api_documents_v1_organizations__organizationid__documents__documentid__delete.md): Deletes a brand document from a brand kit by its reference ID. You can delete a brand document from your brand kit if it’s no longer needed or was uploaded by mistake. This is an irreversible operation. After you delete a document, you cannot retrieve the document or any related information extracted from it.