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

# Guide: Managing Content with Workspaces

> Learn how to organize your documents by creating and managing workspaces using the UBIK API.

This guide will walk you through a common workflow: creating a new workspace, adding a document to it from a URL, and then verifying that the document is correctly associated with the workspace.

<Steps>
  <Step title="Create a New Workspace">
    First, let's create a new workspace to hold our documents. We'll make a `POST` request to the `/workspaces` endpoint. You can give it a name and a description to keep things organized.

    <CodeGroup title="POST /workspaces">
      ```bash cURL theme={null}
      curl -X POST "https://app.ubik-agent.com/api/v1/workspaces" \
           -H "X-API-KEY: YOUR_API_KEY" \
           -H "Content-Type: application/json" \
           -d '{
                "name": "My First Project",
                "description": "Workspace for my first project using the UBIK API."
              }'
      ```

      ```python Python theme={null}
      import requests
      import json

      api_key = "YOUR_API_KEY"
      headers = {
          "X-API-KEY": api_key,
          "Content-Type": "application/json"
      }
      payload = {
          "name": "My First Project",
          "description": "Workspace for my first project using the UBIK API."
      }
      response = requests.post(
          "https://app.ubik-agent.com/api/v1/workspaces",
          headers=headers,
          data=json.dumps(payload)
      )
      print(response.json())
      ```

      ```javascript JavaScript theme={null}
      const apiKey = "YOUR_API_KEY";
      const headers = {
        "X-API-KEY": apiKey,
        "Content-Type": "application/json",
      };
      const body = JSON.stringify({
        name: "My First Project",
        description: "Workspace for my first project using the UBIK API.",
      });

      fetch("https://app.ubik-agent.com/api/v1/workspaces", {
        method: "POST",
        headers: headers,
        body: body,
      })
        .then((response) => response.json())
        .then((data) => console.log(data))
        .catch((error) => console.error("Error:", error));
      ```
    </CodeGroup>

    The API will respond with the details of the newly created workspace, including its unique `id`. Copy this `id` for the next step.

    ```json Response theme={null}
    {
      "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "name": "My First Project",
      "description": "Workspace for my first project using the UBIK API.",
      "is_default": false,
      "created_at": "2025-09-28T14:00:00Z",
      "updated_at": "2025-09-28T14:00:00Z",
      "document_count": 0
    }
    ```
  </Step>

  <Step title="Add a Document to the Workspace">
    Now that we have a workspace, let's add a document to it. You can ingest content from a URL or by uploading a file directly. By passing the `workspace_ids` in the request, the new document will automatically be associated with our newly created workspace.

    <CodeGroup title="POST /documents (from URL)">
      ```bash cURL theme={null}
      curl -X POST "https://app.ubik-agent.com/api/v1/documents" \
           -H "X-API-KEY: YOUR_API_KEY" \
           -F "urls=https://www.ubik-agent.com/" \
           -F "workspace_ids=YOUR_WORKSPACE_ID"
      ```

      ```python Python theme={null}
      import requests

      api_key = "YOUR_API_KEY"
      workspace_id = "YOUR_WORKSPACE_ID" # Replace with the ID from Step 1

      headers = {"X-API-KEY": api_key}
      data = {
          "urls": "https://www.ubik-agent.com/",
          "workspace_ids": workspace_id
      }

      response = requests.post(
          "https://app.ubik-agent.com/api/v1/documents",
          headers=headers,
          data=data
      )

      if response.status_code == 200:
          documents = response.json()
          print("Document being processed:", documents[0]['id'])
      else:
          print(f"Error: {response.status_code}", response.text)
      ```

      ```javascript JavaScript theme={null}
      const apiKey = "YOUR_API_KEY";
      const workspaceId = "YOUR_WORKSPACE_ID"; // Replace with the ID from Step 1
      const url = "https://app.ubik-agent.com/api/v1/documents";

      const formData = new FormData();
      formData.append('urls', 'https://www.ubik-agent.com/');
      formData.append('workspace_ids', workspaceId);

      fetch(url, {
        method: 'POST',
        headers: {
          'X-API-KEY': apiKey
        },
        body: formData
      })
      .then(response => {
        if (!response.ok) {
          throw new Error(`HTTP error: ${response.status}`);
        }
        return response.json();
      })
      .then(documents => {
        console.log('Document being processed:', documents[0].id);
      })
      .catch(error => console.error('Error:', error));
      ```
    </CodeGroup>

    <CodeGroup title="POST /documents (from file)">
      ```bash cURL theme={null}
      curl -X POST "https://app.ubik-agent.com/api/v1/documents" \
           -H "X-API-KEY: YOUR_API_KEY" \
           -F "files=@/path/to/your/file.pdf" \
           -F "workspace_ids=YOUR_WORKSPACE_ID"
      ```

      ```python Python theme={null}
      import requests

      api_key = "YOUR_API_KEY"
      workspace_id = "YOUR_WORKSPACE_ID" # Replace with the ID from Step 1
      file_path = "/path/to/your/file.pdf"

      headers = {"X-API-KEY": api_key}
      data = {"workspace_ids": workspace_id}

      with open(file_path, "rb") as f:
        files = {"files": (file_path, f)}
        response = requests.post(
            "https://app.ubik-agent.com/api/v1/documents",
            headers=headers,
            data=data,
            files=files
        )

      if response.status_code == 200:
          documents = response.json()
          print("Document being processed:", documents[0]['id'])
      else:
          print(f"Error: {response.status_code}", response.text)
      ```

      ```javascript JavaScript theme={null}
      const apiKey = "YOUR_API_KEY";
      const workspaceId = "YOUR_WORKSPACE_ID"; // Replace with the ID from Step 1
      const url = "https://app.ubik-agent.com/api/v1/documents";

      // This example assumes you have a File object.
      // In a browser, you might get this from an <input type="file"> element.
      const myFile = new File(["This is the file content."], "example.txt", {
        type: "text/plain",
      });

      const formData = new FormData();
      formData.append('files', myFile);
      formData.append('workspace_ids', workspaceId);

      fetch(url, {
        method: 'POST',
        headers: {
          'X-API-KEY': apiKey
        },
        body: formData
      })
      .then(response => {
        if (!response.ok) {
          throw new Error(`HTTP error: ${response.status}`);
        }
        return response.json();
      })
      .then(documents => {
        console.log('Document being processed:', documents[0].id);
      })
      .catch(error => console.error('Error:', error));
      ```
    </CodeGroup>

    <Note>
      Document processing is asynchronous. The API will respond immediately with the document details and its status (`pending` or `processing`). You can poll the document endpoint to check when the status changes to `completed`.
    </Note>
  </Step>

  <Step title="Verify Workspace Content">
    Finally, let's confirm our document has been successfully added to the workspace. We'll make a `GET` request to the `/workspaces/{workspace_id}/documents` endpoint.

    <CodeGroup title="GET /workspaces/{workspace_id}/documents">
      ```bash cURL theme={null}
      curl -X GET "https://app.ubik-agent.com/api/v1/workspaces/YOUR_WORKSPACE_ID/documents" \
           -H "X-API-KEY: YOUR_API_KEY"
      ```

      ```python Python theme={null}
      import requests

      api_key = "YOUR_API_KEY"
      workspace_id = "YOUR_WORKSPACE_ID"
      headers = {
          "X-API-KEY": api_key
      }
      response = requests.get(
          f"https://app.ubik-agent.com/api/v1/workspaces/{workspace_id}/documents",
          headers=headers
      )

      if response.status_code == 200:
          workspace_docs = response.json()
          print(workspace_docs)
      else:
          print(f"Error: {response.status_code}", response.text)
      ```

      ```javascript JavaScript theme={null}
      const apiKey = "YOUR_API_KEY";
      const workspaceId = "YOUR_WORKSPACE_ID";
      const headers = {
        "X-API-KEY": apiKey,
      };

      fetch(`https://app.ubik-agent.com/api/v1/workspaces/${workspaceId}/documents`, {
        method: "GET",
        headers: headers,
      })
        .then((response) => {
          if (!response.ok) {
            throw new Error(`HTTP error: ${response.status}`);
          }
          return response.json();
        })
        .then((workspaceDocs) => {
          console.log(workspaceDocs);
        })
        .catch((error) => console.error("Error:", error));
      ```
    </CodeGroup>

    The response will confirm that the document we added in Step 2 is now listed within this workspace.
  </Step>

  <Step title="Retrieve Document Content">
    Once a document has been successfully processed (`status: "completed"`), you can retrieve its content. The API provides a Markdown representation of the document, which is useful for feeding into LLMs or for display.

    <CodeGroup title="GET /documents/{document_id}">
      ```bash cURL theme={null}
      curl -X GET "https://app.ubik-agent.com/api/v1/documents/YOUR_DOCUMENT_ID" \
           -H "X-API-KEY: YOUR_API_KEY"
      ```

      ```python Python theme={null}
      import requests

      api_key = "YOUR_API_KEY"
      document_id = "YOUR_DOCUMENT_ID" # Replace with a processed document's ID

      headers = {"X-API-KEY": api_key}

      response = requests.get(
          f"https://app.ubik-agent.com/api/v1/documents/{document_id}",
          headers=headers
      )

      if response.status_code == 200:
          document_details = response.json()
          print(document_details['markdown_content'])
      else:
          print(f"Error: {response.status_code}", response.text)
      ```

      ```javascript JavaScript theme={null}
      const apiKey = "YOUR_API_KEY";
      const documentId = "YOUR_DOCUMENT_ID"; // Replace with a processed document's ID

      fetch(`https://app.ubik-agent.com/api/v1/documents/${documentId}`, {
        method: "GET",
        headers: { "X-API-KEY": apiKey },
      })
        .then(response => {
          if (!response.ok) {
            throw new Error(`HTTP error: ${response.status}`);
          }
          return response.json();
        })
        .then(documentDetails => {
          console.log(documentDetails.markdown_content);
        })
        .catch(error => console.error("Error:", error));
      ```
    </CodeGroup>

    The response will include the full document details, including the `markdown_content`.
  </Step>
</Steps>

Congratulations! You've successfully created a workspace, added a document, verified its content, and retrieved its processed output. You're now equipped to manage content organization within your UBIK projects.