Skip to main content
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.
1

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.
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."
        }'
The API will respond with the details of the newly created workspace, including its unique id. Copy this id for the next step.
Response
{
  "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
}
2

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.
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"

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"
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.
3

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.
curl -X GET "https://app.ubik-agent.com/api/v1/workspaces/YOUR_WORKSPACE_ID/documents" \
     -H "X-API-KEY: YOUR_API_KEY"
The response will confirm that the document we added in Step 2 is now listed within this workspace.
4

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.
curl -X GET "https://app.ubik-agent.com/api/v1/documents/YOUR_DOCUMENT_ID" \
     -H "X-API-KEY: YOUR_API_KEY"
The response will include the full document details, including the markdown_content.
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.