SomaraGuides, tips & releases

Spaces

API Reference

Spaces API

Manage workspaces programmatically. Spaces organize your work and provide context to AI assistants through RAG (Retrieval-Augmented Generation).

List Spaces

Returns all active spaces in your organization.

GET
/v1/spaces

Authorizations

Authorizationstringheaderrequired

Bearer authentication header of the form `Bearer <token>`

Query Parameters

visibilitystring

Filter by visibility: `public`, `private`, or `archived`

limitinteger

Maximum number of spaces to return (default: 50)

Response

List of spaces in your organization

GETList Spaces
curl --request GET \
  --url https://api.somara.ai/v1/spaces \
  --header 'Authorization: Bearer YOUR_API_KEY'
{
  "success": true,
  "data": [
    {
      "id": 456,
      "name": "Q4 Marketing Campaign",
      "context": "Campaign planning and content...",
      "visibility": "public",
      "rag_enabled": true,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Create Space

Creates a new workspace in your organization.

POST
/v1/spaces

Authorizations

Authorizationstringheaderrequired

Bearer authentication header

Content-Typestringheaderrequired

Must be `application/json`

Request Body

namestringrequired

Display name for the space

contextstring

Background information that will be provided to AI assistants

rag_enabledboolean

Enable document retrieval for this space (default: false)

Response

Space created successfully

POSTCreate Space
curl --request POST \
  --url https://api.somara.ai/v1/spaces \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Product Launch 2024",
    "context": "This space is for coordinating our Q1 product launch. Target market: enterprise SaaS.",
    "rag_enabled": true
  }'
{
  "success": true,
  "data": {
    "id": 458,
    "name": "Product Launch 2024",
    "context": "This space is for coordinating...",
    "visibility": "public",
    "rag_enabled": true
  }
}

Get Space

Retrieves a specific space by its ID.

GET
/v1/spaces/{id}

Authorizations

Authorizationstringheaderrequired

Bearer authentication header

Path Parameters

idintegerrequired

The unique identifier of the space

Response

Space details

GETGet Space
curl --request GET \
  --url https://api.somara.ai/v1/spaces/456 \
  --header 'Authorization: Bearer YOUR_API_KEY'
{
  "success": true,
  "data": {
    "id": 456,
    "name": "Q4 Marketing Campaign",
    "context": "This space is for our Q4 marketing...",
    "visibility": "public",
    "rag_enabled": true,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

Update Space

Updates an existing space. Only include fields you want to change.

PATCH
/v1/spaces/{id}

Authorizations

Authorizationstringheaderrequired

Bearer authentication header

Content-Typestringheaderrequired

Must be `application/json`

Path Parameters

idintegerrequired

The unique identifier of the space

Request Body

namestring

New display name

contextstring

Updated background context

rag_enabledboolean

Toggle document retrieval

visibilitystring

Set to `public` or `private`

Response

Space updated successfully

PATCHUpdate Space
curl --request PATCH \
  --url https://api.somara.ai/v1/spaces/456 \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Q4 Marketing - Final",
    "context": "Updated campaign details..."
  }'
{
  "success": true,
  "data": {
    "id": 456,
    "name": "Q4 Marketing - Final",
    "context": "Updated campaign details..."
  }
}

Archive Space

Archives a space (soft delete). Archived spaces can be restored later.

DELETE
/v1/spaces/{id}

Authorizations

Authorizationstringheaderrequired

Bearer authentication header

Path Parameters

idintegerrequired

The unique identifier of the space to archive

Response

Space archived successfully

DELETEArchive Space
curl --request DELETE \
  --url https://api.somara.ai/v1/spaces/456 \
  --header 'Authorization: Bearer YOUR_API_KEY'
{
  "success": true,
  "message": "Space archived successfully"
}