# 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.

{% tabs %}
{% tab title="Node.js" %}

### 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

{% hint style="info" %}
**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.
{% endhint %}

***

### 1) Create connections (positive & negative)

Create `create-connections.ts`:

```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: "alice@example.com",
            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`:

```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`:

```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`:

```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`:

```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`:

```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):

```ts
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:**

```ts
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:**

```ts
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.
    {% endtab %}
    {% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.gospace.com/start-building/create-connections-and-label-space.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.