Skip to main content
GET
/
api
/
v2
/
platform
/
spaces
/
{space_token}
Get Space by Token
curl --request GET \
  --url http://localhost:3001/api/v2/platform/spaces/{space_token}/ \
  --header 'Authorization: <api-key>' \
  --header 'Org-Handle: <org-handle>'
{
  "status_code": 200,
  "message": "Space fetched successfully",
  "data": {
    "id": "sp_001",
    "name": "Sales Outreach Q1",
    "token": "8KZRTQP7BNW5XEDLORYUHMJC",
    "agent_handle": "space-agent-8qmk42nslp91wrh3dz7btxc4",
    "created_at": "2026-01-10T08:00:00Z"
  }
}

{
  "status_code": 200,
  "message": "Space fetched successfully",
  "data": {
    "id": "sp_001",
    "name": "Sales Outreach Q1",
    "token": "8KZRTQP7BNW5XEDLORYUHMJC",
    "agent_handle": "space-agent-8qmk42nslp91wrh3dz7btxc4",
    "created_at": "2026-01-10T08:00:00Z"
  }
}

​
Get Space by Token

Retrieve configuration and metadata of a specific space identified by its token. This allows you to view a space’s current setup, properties, and organization context.

​
Headers

NameTypeRequiredDescription
AuthorizationstringYesAPI Key format: Token <token>
Org-HandlestringYesOrganization domain handle

​
Response Fields

FieldTypeDescription
status_codeintegerHTTP status code
messagestringResponse message
dataobjectSpace object details

​
Space Object Fields

FieldTypeDescription
idstringUnique space identifier
namestringSpace display name
tokenstringPublic token for API access
agent_handlestringHandle of the agent assigned to this space
created_atstringSpace creation timestamp (ISO 8601)

​
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 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}`);
  console.log(`Agent handle: ${response.data.data.agent_handle}`);
  return response.data.data;
};

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

​
Best Practices

  1. Space Token: Ensure you are using a valid space token from your organization
  2. Org-Handle: Always include the correct organization handle in requests
  3. Error Handling: Handle 404 responses when a space token may have been deleted or is invalid
  4. Security: Keep API tokens secure and rotate them regularly
  5. Caching: Consider caching space details to avoid repeated lookups for the same space

Authorizations

​
Authorization
string
header
required

Format: Token

Headers

​
Org-Handle
string
required

Organization domain handle

Example:

"unpod"

Path Parameters

​
space_token
string
required
Example:

"8KZRTQP7BNW5XEDLORYUHMJC"

Response

Space details