Create connections and label space

Set positive or negative relationships between people, teams, and spaces, and tag spaces with labels to guide AI allocation decisions.

Prerequisites

Completed Setup Your Development Environment and Send Your First API Request
Node.js v18+ and npm v9+
A valid gospace API key in your .env file
Known IDs (or external IDs) for the entities you want to relate

Allowed connection entity types: TEAM, PERSON, LABEL, SPACE, ROOM, ZONE. Strength is an integer (e.g., -100 → 100). Negative is an avoid signal; positive is a prefer signal.

1) Create connections (positive & negative)

Create create-connections.ts:

import "dotenv/config";
import GospaceAI from "@gospace-ai/api";

async function main() {
  const gospace = new GospaceAI(process.env.GOSPACE_API_KEY!);

  const res = await gospace.connections.createConnections({
    connections: [
      // Positive: person prefers to sit near a team
      {
        strength: 75,
        connection_from_entity: {
          connection_entity_id: "person_123",
          connection_entity_type: "PERSON",
          connection_entity_data: {
            first_name: "Alice",
            last_name: "Smith",
            email: "[email protected]",
            person_id: "person_123",
            external_id: "ext-alice",
          },
        },
        connection_to_entity: {
          connection_entity_id: "team_456",
          connection_entity_type: "TEAM",
          connection_entity_data: {
            team_name: "Engineering",
            team_id: "team_456",
            external_id: "ext-team-eng",
          },
        },
      },

      // Negative: team should avoid a particular room
      {
        strength: -50,
        connection_from_entity: {
          connection_entity_id: "team_456",
          connection_entity_type: "TEAM",
          connection_entity_data: {
            team_name: "Engineering",
            team_id: "team_456",
          },
        },
        connection_to_entity: {
          connection_entity_id: "room_789",
          connection_entity_type: "ROOM",
          connection_entity_data: {
            room_name: "Conference Room A",
            room_id: "room_789",
          },
        },
      },
    ],
  });

  console.log(JSON.stringify(res.data.connections, null, 2));
}

main().catch((err) => {
  console.error("Create connections failed:", err);
  process.exit(1);
});

2) Query connections (by entity, type, or external_id)

Create get-connections.ts:

import "dotenv/config";
import GospaceAI from "@gospace-ai/api";

async function main() {
  const gospace = new GospaceAI(process.env.GOSPACE_API_KEY!);

  // Examples of useful filters:
  const res = await gospace.connections.getConnections({
    // connection_id: "conn_123", // exact connection
    connection_entity_id: "team_456", // find all touching this entity
    connection_entity_type: "TEAM",   // TEAM | PERSON | LABEL | SPACE | ROOM | ZONE
    // external_id: "ext-alice",     // match external_id of PERSON/TEAM in from/to entities
    skip: 0,
    limit: 25,
    sort: "strength",
    order: "desc",
  });

  console.log(JSON.stringify(res.data.connections, null, 2));
}

main().catch((err) => {
  console.error("Get connections failed:", err);
  process.exit(1);
});

3) Update connection strength / endpoints

Create update-connections.ts:

import "dotenv/config";
import GospaceAI from "@gospace-ai/api";

async function main() {
  const gospace = new GospaceAI(process.env.GOSPACE_API_KEY!);

  const res = await gospace.connections.updateConnections({
    connections: [
      {
        _id: "conn_abc123",     // the connection to update
        strength: 90,           // new strength (e.g., boost preference)
        connection_from_entity: {
          connection_entity_id: "person_123",
          connection_entity_type: "PERSON",
        },
        connection_to_entity: {
          connection_entity_id: "team_456",
          connection_entity_type: "TEAM",
        },
      },
    ],
  });

  console.log(JSON.stringify(res.data.connections, null, 2));
}

main().catch((err) => {
  console.error("Update connections failed:", err);
  process.exit(1);
});

4) Delete connections

Create delete-connections.ts:

import "dotenv/config";
import GospaceAI from "@gospace-ai/api";

async function main() {
  const gospace = new GospaceAI(process.env.GOSPACE_API_KEY!);

  const res = await gospace.connections.deleteConnections({
    connections: [
      { connection_id: "conn_abc123" },
      { connection_id: "conn_def456" },
    ],
  });

  console.log(JSON.stringify(res.data, null, 2));
}

main().catch((err) => {
  console.error("Delete connections failed:", err);
  process.exit(1);
});

5) Create labels (for tagging entities)

Create create-labels.ts:

import "dotenv/config";
import GospaceAI from "@gospace-ai/api";

async function main() {
  const gospace = new GospaceAI(process.env.GOSPACE_API_KEY!);

  const res = await gospace.connections.createLabels({
    labels: [
      {
        name: "Quiet",
        type: "category",
        details: { color: "blue", description: "Quiet working area" },
      },
      {
        name: "Exec",
        type: "tag",
        details: { color: "gold", description: "Executive seating" },
      },
    ],
  });

  console.log(JSON.stringify(res.data.labels, null, 2));
}

main().catch((err) => {
  console.error("Create labels failed:", err);
  process.exit(1);
});

6) Label space (map a label to SPACE/ROOM/ZONE/TEAM/PERSON)

Create map-labels.ts:

import "dotenv/config";
import GospaceAI from "@gospace-ai/api";

async function main() {
  const gospace = new GospaceAI(process.env.GOSPACE_API_KEY!);

  const res = await gospace.connections.createLabelMappings({
    mappings: [
      // Label a space as "Quiet"
      {
        label_id: "label_quiet",
        entity_id: "space_101",
        entity_type: "SPACE", // TEAM | PERSON | LABEL | SPACE | ROOM | ZONE
        details: { applied_at: new Date().toISOString() },
      },

      // Label a room as "Exec"
      {
        label_id: "label_exec",
        entity_id: "room_789",
        entity_type: "ROOM",
        details: { applied_at: new Date().toISOString() },
      },
    ],
  });

  console.log(JSON.stringify(res.data.mappings, null, 2));
}

main().catch((err) => {
  console.error("Create label mappings failed:", err);
  process.exit(1);
});

7) Query & manage label mappings

Get mappings (filter by label, entity, type, or external_id):

const mappings = await gospace.connections.getLabelMappings({
  // mapping_id: "map_123",
  label_id: "label_quiet",
  entity_type: "SPACE",
  skip: 0,
  limit: 25,
  sort: "label_id",
  order: "asc",
});
console.log(JSON.stringify(mappings.data.mappings, null, 2));

Update mappings:

await gospace.connections.updateLabelMappings({
  mappings: [
    {
      _id: "map_123",
      label_id: "label_quiet",
      entity_id: "space_101",
      entity_type: "SPACE",
      details: { applied_at: new Date().toISOString(), note: "Near windows" },
    },
  ],
});

Delete mappings:

await gospace.connections.deleteLabelMappings({
  mappings: [{ mapping_id: "map_123" }],
});

Tips & patterns

Model behaviour:
- Positive connections (> 0) indicate affinity or proximity preference.
- Negative connections (< 0) indicate separation or avoidance.
Granularity:
- Use people ↔ team for day‑to‑day seating preferences.
- Use team ↔ room/zone/space for capacity and neighborhood tuning.
- Use labels to tag assets (e.g., “Quiet”, “Client‑facing”, “Accessible”).
Searchability:
- Use external_id on people/teams, then query getConnections with external_id to keep your system in sync.
Governance:
- Keep connection strengths within a standard range (e.g., -100, -50, -25, 25, 50, 100) so they’re interpretable.
- Periodically audit old connections and label mappings to avoid stale constraints.

Last updated 15 days ago

Was this helpful?