Skip to main content

​
Spaces API

The Spaces API allows you to manage and retrieve spaces (workspaces/groups) in your Unpod platform. Spaces are containers that organize your tasks, runs, and data collections.
Prerequisites: Make sure you have your API Token and Org-Handle ready. See Authentication for details.

​
Get All Spaces

Retrieve details of all created spaces, allowing you to view and manage workspace/group entities in the system. 
GET /api/v2/platform/spaces/

​
Headers

NameTypeRequiredDescription
AuthorizationstringYesAPI Key format: Token <token>
Org-HandlestringYesOrganization domain handle
You can get the Org-Handle by hitting the Get All Organizations API. The domain_handle field in the response is your Org-Handle.

​
Example Request

GET /api/v2/platform/spaces/
Headers:
  Authorization: Token your-api-token
  Org-Handle: your-org-handle

​
Success Response (200)

{
  "count": 207,
  "status_code": 200,
  "message": "Spaces fetched successfully",
  "data": [
    {
      "name": "abcd evals",
      "slug": "abcd-evals-3ivqicbp",
      "token": "8KZAMRAHSXXXXXXMAYNASMJC",
      "description": "",
      "logo": null,
      "privacy_type": "shared",
      "space_type": "knowledge_base",
      "content_type": "table",
      "organization": {
        "name": "Unpod TV",
        "domain_handle": "recalll.co"
      }
    }
  ]
}

​
Response Fields

FieldTypeDescription
countintegerTotal number of spaces
status_codeintegerHTTP status code
messagestringResponse message
dataarrayArray of space objects

​
Space Object Fields

FieldTypeDescription
namestringSpace name
slugstringURL-friendly unique identifier
tokenstringPublic token for API access
descriptionstringSpace description
logostringLogo URL (null if not set)
privacy_typestringPrivacy setting: shared, private
space_typestringType of space: knowledge_base, etc.
content_typestringContent type: table, etc.
organizationobjectOrganization details (name, domain_handle)

​
Error Response (401  Unauthorized)

{
  "status_code": 401,
  "message": "Authentication credentials were not provided."
}

​
Get Space by Token

Retrieve configuration and metadata of a specific space identified by its token, allowing you to view its current setup and properties. 
GET /api/v2/platform/spaces/{space_token}/

​
Path Parameters

NameTypeRequiredDescription
space_tokenstringYesPublic token identifying the space
You can get the space_token by hitting the Get All Spaces API. The token field in the response is your Space Token.

​
Headers

NameTypeRequiredDescription
AuthorizationstringYesAPI Key format: Token <token>
Org-HandlestringYesOrganization domain handle
You can get the Org-Handle by hitting the Get All Organizations API. The domain_handle field in the response is your Org-Handle.

​
Example Request

GET /api/v2/platform/spaces/8KZRTQP7BNW5XEDLORYUHMJC/
Headers:
  Authorization: Token your-api-token
  Org-Handle: your-org-handle

​
Success Response (200)

{
  "status_code": 200,
  "message": "Space fetched successfully",
  "data": {
    "name": "abcd evals",
    "slug": "abcd-evals-3ivqicbp",
    "token": "8KZRTQP7BNW5XEDLORYUHMJC",
    "description": "",
    "logo": null,
    "privacy_type": "shared",
    "space_type": "knowledge_base",
    "content_type": "table",
    "organization": {
      "name": "Unpod TV",
      "domain_handle": "recalll.co"
    }
  }
}

​
Response Fields

FieldTypeDescription
status_codeintegerHTTP status code
messagestringResponse message
dataobjectSpace object details

​
Error Response (401  Unauthorized)

{
  "status_code": 401,
  "message": "Authentication credentials were not provided."
}

​
Error Response (404  Not Found)

{
  "status_code": 404,
  "message": "Space not found."
}

​
Common Error Codes

Status CodeDescription
200Success - Request completed successfully
400Bad Request - Invalid parameters provided
401Unauthorized - Invalid or missing API token
403Forbidden - Access denied to the resource
404Not Found - Space or Organization not found
500Internal Server Error - Server-side error

​
Code Examples

const axios = require('axios');

const headers = {
  'Authorization': 'Token your-api-token',
  'Org-Handle': 'your-org-handle'
};

// Get all spaces
const getAllSpaces = async () => {
  const response = await axios.get(
    'https://unpod.dev/api/v2/platform/spaces/',
    { headers }
  );
  console.log(`Total spaces: ${response.data.count}`);
  return response.data.data;
};

// Get space by token
const getSpaceByToken = async (spaceToken) => {
  const response = await axios.get(
    `https://unpod.dev/api/v2/platform/spaces/${spaceToken}/`,
    { headers }
  );
  console.log(`Space name: ${response.data.data.name}`);
  return response.data.data;
};

// Example usage
getAllSpaces();
getSpaceByToken('8KZRTQP7BNW5XEDLORYUHMJC');

​
Best Practices

  1. Org-Handle: Always include the correct organization handle in requests that require it
  2. Space Token: Use the space token for accessing specific space resources
  3. Error Handling: Always handle potential errors and edge cases
  4. Security: Keep API tokens secure and rotate them regularly
  5. Caching: Consider caching space/organization data to reduce API calls