Spaces

A space is a shared workspace that gathers the records about one subject, such as a customer account or a project. You add contacts and organizations to it directly, and you choose tags: anything carrying one of those tags belongs to the space too, as do the tasks attached to its contacts and organizations. Use this resource to set up spaces, decide who can see them, and read what they contain.

A space is visible to your key when your key’s user created it, was added to it directly or through a group, or when it is public. Only the space’s admins can change or delete it: its creator, and the members listed in admin_user_ids.

#The space object

Returned by every space endpoint. List responses fill in counts and leave the content previews (tasks, events, contacts, organizations) null; retrieving a single space fills in both.

Attributes

  • idstring · uuid

    Unique identifier for the space.

  • namestring
  • descriptionstring · nullable
  • publicboolean · nullable

    Whether everyone in the account can see the space. Spaces created through the API are not public.

  • include_tagged_resource_childrenboolean

    Despite the name, this controls threads and files reached through the space’s directly added contacts and organizations. When true, the space also includes email threads with its contacts and with people employed by its organizations, and the files attached to those threads. When false, it includes only the threads and files that carry one of its tags.

  • inclusionsobject

    What was added to the space. Each entry has an id and name. Contacts not visible to your key are left out.

    Show 3 child attributesHide child attributes
    • tagsarray of objects

      The space’s tags.

    • contactsarray of objects

      Contacts added directly.

    • organizationsarray of objects

      Organizations added directly.

  • pinnedboolean · nullable

    Whether your key’s user has pinned this space.

  • created_by_user_idstring · uuid · nullable

    The user who created the space. The creator is always an admin.

  • admin_user_idsarray of strings · uuid · nullable

    Every user who can change or delete the space: the creator plus the members flagged as admins.

  • usersarray of users · nullable

    Users added to the space directly.

  • groupsarray of groups · nullable

    Groups added to the space, each with its members. Every member can see the space; none is an admin through the group.

  • countsobject

    How many records of each kind the space holds. Absent from the response to Create a space.

    Show 9 child attributesHide child attributes
    • tasksinteger · nullable

      Open tasks in the space that are visible to your key.

    • open_tasksinteger · nullable

      Open tasks in the space. Null in lists.

    • eventsinteger · nullable

      In a list, all calendar events in the space. On a single space, upcoming events.

    • upcoming_eventsinteger · nullable

      Calendar events from today on. Null in lists.

    • contactsinteger · nullable
    • organizationsinteger · nullable
    • threadsinteger · nullable
    • filesinteger · nullable
    • commentsinteger · nullable
  • tasksarray of tasks · nullable

    Single space only: up to five open tasks in the space, soonest due first. Get the rest with List tasks and space_id.

  • eventsarray of calendar events · nullable

    Single space only: up to three upcoming calendar events in the space.

  • contactsarray of contacts · nullable

    Single space only: every contact in the space, added directly or through a tag.

  • organizationsarray of organizations · nullable

    Single space only: every organization in the space, added directly or through a tag.

The space object 
{
  "id": "a7b45815-8c9d-4f5a-86dc-0008ebcb1a9b",
  "name": "Wildgrove account",
  "description": "Everything for the Wildgrove renewal and the 2027 rollout.",
  "public": false,
  "include_tagged_resource_children": true,
  "inclusions": {
    "tags": [
      { "id": "0f1e2d3c-4b5a-4968-8776-655443322110", "name": "Customer" }
    ],
    "contacts": [
      { "id": "1f3c9a52-7b0e-4d4a-9c1e-2a6f0d8b3e41", "name": "Priya Natarajan" }
    ],
    "organizations": [
      { "id": "6b0e2d9a-4c31-4f8e-a7d2-90c4e1b7f5a3", "name": "Wildgrove Property Management" }
    ]
  },
  "pinned": true,
  "created_by_user_id": "9c41d2e8-3f6a-4b7c-8d1e-5a2f7b9c0d3e",
  "admin_user_ids": ["9c41d2e8-3f6a-4b7c-8d1e-5a2f7b9c0d3e"],
  "users": [
    { "id": "44c3f6da-393b-4664-9bfa-3c14e76b8cb8", "first_name": "Marcus", … }
  ],
  "groups": [
    { "id": "6dd53ebb-eb27-4724-80dd-c172b7d75a49", "name": "Finance", … }
  ],
  "counts": {
    "tasks": 4,
    "open_tasks": 4,
    "upcoming_events": 2,
    "events": 2,
    "contacts": 6,
    "organizations": 1,
    "threads": 58,
    "files": 11,
    "comments": 3
  },
  "tasks": [
    { "id": "0361c1d0-a72d-43bc-86c1-26537f0236ec", "assignment": "Confirm headcount for the 2027 contract", … },
    …
  ],
  "events": [
    { "id": "9b310b6a-d686-4b27-9af4-16f9734aec81", "name": "Wildgrove renewal review", … },
    …
  ],
  "contacts": [
    { "id": "1f3c9a52-7b0e-4d4a-9c1e-2a6f0d8b3e41", "name": "Priya Natarajan", … },
    …
  ],
  "organizations": [
    { "id": "6b0e2d9a-4c31-4f8e-a7d2-90c4e1b7f5a3", "name": "Wildgrove Property Management", … }
  ]
}
get/spaces Read key

#List spaces

Returns every matching space visible to your key in one response, with its members and counts, sorted by name; the list isn’t paginated.

Query parameters

  • querystring

    Match against the space’s name and description.

  • slicestring

    pinned: spaces your key’s user has pinned. public: public spaces. private: spaces that aren’t public, including ones shared with members. mine: spaces your key’s user created.

    pinnedpublicprivatemine
  • sortstringdefault name

    Field to sort by. Any other value falls back to name.

    namecreated_atupdated_at
  • orderstringdefault asc
    ascdesc

Returns

  • collectionobject
    Show 5 child attributesHide child attributes
    • recordsarray of spaces
    • total_resultsinteger · nullable

      The number of spaces returned.

    • slice_keystring · nullable

      The slice that was applied.

    • sortstring · nullable

      The sort that was applied.

    • orderstring · nullable

      The order that was applied.

get/spaces 
curl "https://api.carom.io/spaces?slice=mine&sort=updated_at&order=desc" \
  -H "Authorization: Bearer $CAROM_API_KEY"
Response200 
{
  "collection": {
    "slice_key": "mine",
    "sort": "updated_at",
    "order": "desc",
    "total_results": 2,
    "records": [
      {
        "id": "a7b45815-8c9d-4f5a-86dc-0008ebcb1a9b",
        "name": "Wildgrove account",
        "counts": {
          "tasks": 9,
          "open_tasks": null,
          "upcoming_events": null,
          "events": 14,
          "contacts": 6,
          "organizations": 1,
          "threads": 58,
          "files": 11,
          "comments": 7
        },
        "tasks": null,
        …
      },
      {
        "id": "2c244e2d-5e97-4f9e-bb4d-cc163cc7c7db",
        "name": "2027 planning",
        …
      }
    ]
  }
}
post/spaces Write key

#Create a space

Creates a space with your key’s user as its creator and first admin. The creator can see and administer the space without being listed in user_ids.

Every list field must be present, but each can be null or empty. User and group ids outside your account, and tags, contacts, and organizations not visible to your key, are ignored; the response shows which were added.

Headers

  • Idempotency-Keystring

    A key you choose, 1 to 255 printable ASCII characters, that makes the request safe to retry. When your key’s user repeats a request to this endpoint with the same key within 24 hours of a successful one, Carom returns the first response again instead of creating a second space. The request body isn’t compared, so use a new key for each new space. A failed request doesn’t use up its key.

Request body application/json

  • spaceobjectrequired
    Show 9 child attributesHide child attributes
    • namestringrequired
    • descriptionstring
    • include_tagged_resource_childrenbooleanrequired

      Whether to include threads and files through the space’s contacts and organizations. See the space object.

    • tag_idsarray of strings · uuid · nullablerequired

      Tags whose records belong to the space.

    • contact_idsarray of strings · uuid · nullablerequired
    • organization_idsarray of strings · uuid · nullablerequired
    • user_idsarray of strings · uuid · nullablerequired

      Users to add as members.

    • group_idsarray of strings · uuid · nullablerequired

      Groups whose members can see the space.

    • admin_user_idsarray of strings · uuid

      Which of user_ids are admins. Ids not also in user_ids are ignored. Omit to make every member a regular member.

Returns

The new space object without counts or content previews, wrapped in space, with status 201.

Errors

  • 400invalid_requestA field failed validation, for example a missing name or list field or an id that isn’t a UUID, or the Idempotency-Key header is malformed. error.fields says which.
  • 409idempotency_key_in_useA request with the same Idempotency-Key is still in progress. Retry shortly.
post/spaces 
curl https://api.carom.io/spaces \
  -H "Authorization: Bearer $CAROM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4e9d1b7a-3c52-4a08-8f6e-0d7c2b9a5e31" \
  -d '{
    "space": {
      "name": "Wildgrove account",
      "description": "Everything for the Wildgrove renewal and the 2027 rollout.",
      "include_tagged_resource_children": true,
      "tag_ids": ["0f1e2d3c-4b5a-4968-8776-655443322110"],
      "contact_ids": ["1f3c9a52-7b0e-4d4a-9c1e-2a6f0d8b3e41"],
      "organization_ids": ["6b0e2d9a-4c31-4f8e-a7d2-90c4e1b7f5a3"],
      "user_ids": ["44c3f6da-393b-4664-9bfa-3c14e76b8cb8"],
      "group_ids": ["6dd53ebb-eb27-4724-80dd-c172b7d75a49"]
    }
  }'
Response201 
{
  "space": {
    "id": "a7b45815-8c9d-4f5a-86dc-0008ebcb1a9b",
    "name": "Wildgrove account",
    "public": false,
    "include_tagged_resource_children": true,
    "created_by_user_id": "9c41d2e8-3f6a-4b7c-8d1e-5a2f7b9c0d3e",
    "admin_user_ids": ["9c41d2e8-3f6a-4b7c-8d1e-5a2f7b9c0d3e"],
    "tasks": null,
    …
  }
}
get/spaces/{id} Read key

#Retrieve a space

Returns a single space with its members, counts, and previews of its content: its contacts and organizations, up to five open tasks, and up to three upcoming calendar events. Content not visible to your key is left out.

Path parameters

  • idstring · uuidrequired

    The space’s id.

Returns

The space object, wrapped in space.

Errors

  • 404record_not_foundNo space with that id is visible to your key.
get/spaces/{id} 
curl https://api.carom.io/spaces/a7b45815-8c9d-4f5a-86dc-0008ebcb1a9b \
  -H "Authorization: Bearer $CAROM_API_KEY"
Response200 
{
  "space": {
    "id": "a7b45815-8c9d-4f5a-86dc-0008ebcb1a9b",
    "name": "Wildgrove account",
    …
    "counts": {
      "tasks": 4,
      "open_tasks": 4,
      "upcoming_events": 2,
      …
    },
    "tasks": [
      {
        "id": "0361c1d0-a72d-43bc-86c1-26537f0236ec",
        "assignment": "Confirm headcount for the 2027 contract",
        "due": "2026-09-18",
        …
      }
    ],
    …
  }
}
patch/spaces/{id} Write key

#Update a space

Changes a space’s details, members, and contents. Only admins of the space can update it.

Changes the fields you send and leaves the rest alone. For each list field, an array replaces the list with exactly those ids and null clears it. For tag_ids, contact_ids, and organization_ids, this applies only to records visible to your key: ids of records your key can’t see are ignored, and such records already in the space stay in it. null also clears description; name and include_tagged_resource_children can’t be null.

When you send admin_user_ids, it sets the admin flag of every remaining member: members in the list become admins and the rest become regular members. Sent without user_ids, it applies to the current members. Omit it to keep the current admins. The creator is always an admin.

An update that removes your key’s user from the space is saved like any other.

Path parameters

  • idstring · uuidrequired

Request body application/json

  • spaceobjectrequired

    Any of the attributes accepted by Create a space. None is required.

Returns

The updated space object, as Retrieve a space returns it, wrapped in space.

Errors

  • 400invalid_requestA field failed validation, for example an empty or null name. error.fields says which.
  • 403permission_deniedThe space is visible to your key, but your key’s user isn’t one of its admins. Nothing is changed.
  • 404record_not_foundNo space with that id is visible to your key.
patch/spaces/{id} 
curl -X PATCH https://api.carom.io/spaces/a7b45815-8c9d-4f5a-86dc-0008ebcb1a9b \
  -H "Authorization: Bearer $CAROM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "space": {
      "user_ids": [
        "44c3f6da-393b-4664-9bfa-3c14e76b8cb8",
        "ea5f6800-b2b7-4df4-a5e9-3a4ed2d84961"
      ],
      "admin_user_ids": ["44c3f6da-393b-4664-9bfa-3c14e76b8cb8"]
    }
  }'
Response200 
{
  "space": {
    "id": "a7b45815-8c9d-4f5a-86dc-0008ebcb1a9b",
    "name": "Wildgrove account",
    "created_by_user_id": "9c41d2e8-3f6a-4b7c-8d1e-5a2f7b9c0d3e",
    "admin_user_ids": [
      "9c41d2e8-3f6a-4b7c-8d1e-5a2f7b9c0d3e",
      "44c3f6da-393b-4664-9bfa-3c14e76b8cb8"
    ],
    "users": [
      { "id": "44c3f6da-393b-4664-9bfa-3c14e76b8cb8", "first_name": "Marcus", … },
      { "id": "ea5f6800-b2b7-4df4-a5e9-3a4ed2d84961", "first_name": "Elena", … }
    ],
    …
  }
}
delete/spaces/{id} Write key

#Delete a space

Deletes the space, along with the comments left on the space itself and the tasks added to it directly (tasks whose space_id is this space). Contacts, organizations, and records that belonged to the space through a tag are not deleted. Only admins of the space can delete it. Deletion is permanent.

Path parameters

  • idstring · uuidrequired

Returns

An empty response with status 204.

Errors

  • 403permission_deniedThe space is visible to your key, but your key’s user isn’t one of its admins.
  • 404record_not_foundNo space with that id is visible to your key.
delete/spaces/{id} 
curl -X DELETE https://api.carom.io/spaces/2c244e2d-5e97-4f9e-bb4d-cc163cc7c7db \
  -H "Authorization: Bearer $CAROM_API_KEY"
Response204 
No content
get/spaces/{id}/discussion Read key

#Retrieve a space’s discussion

Returns the internal comments your team has left on the space and on the records in it, grouped into scopes: one for the space itself, then one each for its people, organizations, deals, emails, files, and events. A scope other than the space’s own appears only when at least one record in it has comments. Comments on records not visible to your key are left out. Every visible comment is included; the discussion isn’t paginated.

To post a comment on the space, use Create a comment.

Path parameters

  • idstring · uuidrequired

Returns

  • discussionobject
    Show 1 child attributeHide child attributes
    • scopesarray of objects

      The space’s own scope first, then the others.

      Show 6 child attributesHide child attributes
      • keystring
        spacepeopleorganizationsdealsemailsfilesevents
      • labelstring

        A heading for the scope, such as This space. Display text; use key to identify a scope.

      • unitstring

        A plural noun for the scope’s records, for display, such as people.

      • primaryboolean

        True for the space’s own scope.

      • total_commentsinteger
      • recordsarray of objects

        The records in the scope that have comments, most recently discussed first.

        Show 6 child attributesHide child attributes
        • keystring

          record_type and record_id joined with a hyphen.

        • record_typestring
          spacecontactorganizationdealthreadfilecalendar_event
        • record_idstring · uuid
        • namestring · nullable
        • total_commentsinteger
        • commentsarray of comments

          Oldest first.

Errors

  • 404record_not_foundNo space with that id is visible to your key.
get/spaces/{id}/discussion 
curl https://api.carom.io/spaces/a7b45815-8c9d-4f5a-86dc-0008ebcb1a9b/discussion \
  -H "Authorization: Bearer $CAROM_API_KEY"
Response200 
{
  "discussion": {
    "scopes": [
      {
        "key": "space",
        "label": "This space",
        "unit": "spaces",
        "primary": true,
        "total_comments": 1,
        "records": [
          {
            "key": "space-a7b45815-8c9d-4f5a-86dc-0008ebcb1a9b",
            "record_type": "space",
            "record_id": "a7b45815-8c9d-4f5a-86dc-0008ebcb1a9b",
            "name": "Wildgrove account",
            "total_comments": 1,
            "comments": [
              {
                "id": "2537b086-4ff8-47e6-856b-eff69ff703d7",
                "html_content": "<p>Renewal call moved to the 22nd. Agenda is in the shared folder.</p>",
                "text": null,
                "user_id": "9c41d2e8-3f6a-4b7c-8d1e-5a2f7b9c0d3e",
                "space_id": "a7b45815-8c9d-4f5a-86dc-0008ebcb1a9b",
                "created_at": "2026-09-15T14:05:37.315Z",
                …
              }
            ]
          }
        ]
      },
      {
        "key": "people",
        "label": "People",
        "unit": "people",
        "primary": false,
        "total_comments": 2,
        "records": [
          {
            "key": "contact-1f3c9a52-7b0e-4d4a-9c1e-2a6f0d8b3e41",
            "record_type": "contact",
            "record_id": "1f3c9a52-7b0e-4d4a-9c1e-2a6f0d8b3e41",
            "name": "Priya Natarajan",
            "total_comments": 2,
            "comments": […]
          }
        ]
      }
    ]
  }
}