@gospace-ai/api

Official TypeScript SDK for gospace AI services covered by the current schemas: Authentication, Directory, Spatial, and System.

This README only documents endpoints that are defined in the attached OpenAPI specs (auth.yml, directory.yml, spatial.yml, system.yml). We’ll add other modules later.

Features

• TypeScript-first — Typed request/response helpers for the covered services.
• Simple initialization — Provide your API key; optional base URL override for sandbox/testing.
• Pagination helpers — Most list endpoints accept skip, limit, sort, order.

Installation

# Node 18+ (recommended — has global fetch)
npm install @gospace-ai/api

# Node < 18 or environments without fetch
npm install @gospace-ai/api cross-fetch

The SDK is written in TypeScript and supports Node.js ≥ 12. For best results and native fetch support, use Node.js ≥ 18 LTS.

Authentication & Security

• Your API key is sent on every request as the x-api-key header.
• Do not expose API keys in the browser. Route calls through your backend if you have a web client.
• The Authentication API issues short‑lived SDK tokens (e.g., for the Floorplan SDK).

Quick Start

Create a .env:

GOSPACE_API_KEY=your_api_key_here

Initialize the client:

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

const apiKey = process.env.GOSPACE_API_KEY!;

// Default base URL: https://api.gospace.app
const gospace = new GospaceAI(apiKey);

// Optional: override base URL for sandbox/testing
// const gospace = new GospaceAI(apiKey, { url: "https://sandbox.api.gospace.app" });

ESM / CommonJS

ESM (recommended)

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

CommonJS

const GospaceAI = require("@gospace-ai/api").default;

Authentication API (auth.yml)

Generate SDK Access Token

POST /sdk/token

const tokenRes = await gospace.authentication.generateSdkToken({
  email: "[email protected]", // required, format: email
});

console.log(tokenRes.data.access_token); // "<JWT Access Token>"

Response shape (200):

{
  success: true,
  data: { access_token: string },
  identifier: "auth_successful"
}

Directory API (directory.yml)

People

GET /people — list/filter people

Supported query params include: person_id, email, first_name, last_name, external_id, skip, limit, sort, order.

const peopleRes = await gospace.directory.getPeople({
  skip: 0,
  limit: 10,
  sort: "email",
  order: "asc",
});
console.log(peopleRes.data.people);

POST /people — create people

const createPeople = await gospace.directory.createPeople({
  people: [
    {
      email: "[email protected]",
      first_name: "Alice",
      last_name: "Smith",
      external_id: "ext-alice-1", // optional
    },
  ],
});
console.log(createPeople.data.people);

PUT /people — update people (by people_id inside each object)

const updatePeople = await gospace.directory.updatePeople({
  people: [
    {
      people_id: "person_123",
      first_name: "Alicia",
      last_name: "Smith",
      external_id: "ext-alicia-1",
    },
  ],
});

DELETE /people — delete people

await gospace.directory.deletePeople({
  people: [{ people_id: "person_123" }],
});

Teams

GET /teams — list/filter teams

Supports: team_id, team_name, external_id, include_members, skip, limit, sort, order.

const teamsRes = await gospace.directory.getTeams({
  include_members: true,
  skip: 0,
  limit: 10,
});
console.log(teamsRes.data.teams);

POST /teams — create teams

const createTeams = await gospace.directory.createTeams({
  teams: [
    { team_name: "Planning", external_id: "ext-planning-1" },
  ],
});

PUT /teams — update teams

const updateTeams = await gospace.directory.updateTeams({
  teams: [
    { team_id: "team_123", team_name: "Planning & Strategy", external_id: "ext-plan-2" },
  ],
});

DELETE /teams — delete teams

await gospace.directory.deleteTeams({
  teams: [{ team_id: "team_123" }],
});

Team Members

GET /teams/{team_id}/members — list members of a team Supports filters: people_id, external_id, email, first_name, last_name, skip, limit, sort, order.

const teamMembers = await gospace.directory.getTeamMembers("team_123", {
  skip: 0,
  limit: 25,
});
console.log(teamMembers.data.members);

PUT /teams/{team_id}/members — add members

await gospace.directory.addTeamMembers("team_123", {
  members: [{ people_id: "person_456" }],
});

DELETE /teams/{team_id}/members — remove members

await gospace.directory.removeTeamMembers("team_123", {
  members: [{ people_id: "person_456" }],
});

Spatial API (spatial.yml)

Uniform CRUD across spatial entities defined in the schema:

• /locations
• /layers
• /spaces
• /rooms
• /zones
• /clusters
• /areas
• /layer/circulation

Each path supports GET, POST, PUT, DELETE with consistent body shapes (plural arrays for create/update/delete). Most GETs accept skip, limit, sort, order plus entity-specific filters.

Locations

GET /locations — list/filter locations

const locations = await gospace.spatial.getLocations({ skip: 0, limit: 5 });
console.log(locations.data.locations);

POST /locations — create locations

const newLocations = await gospace.spatial.createLocations({
  locations: [
    {
      name: "New Office",
      country: {
        country_id: "GB_ID",
        name: "United Kingdom",
        iso2: "GB",
        selected_timezone: "Europe/London",
        timezones: ["Europe/London"],
      },
      address: {
        postal_code: "EC2V 6DN",
        country_name: "UK",
        line1: "1 Example St",
        line2: "Suite 100",
      },
      coords: { latitude: 51.514, longitude: -0.093 },
      external_id: "new-office-1",
    },
  ],
});
console.log(newLocations.data.locations);

PUT /locations — update locations

const updated = await gospace.spatial.updateLocations({
  locations: [
    { location_id: "loc_123", name: "HQ London" },
  ],
});

DELETE /locations — delete locations

await gospace.spatial.deleteLocations({
  locations: [{ location_id: "loc_123" }],
});

The same list/create/update/delete patterns apply to layers, spaces, rooms, zones, clusters, areas, and layer/circulation, following the schemas provided in spatial.yml.

System API (system.yml)

Countries

GET /country

const countries = await gospace.system.getCountries();
console.log(countries.data);

File Uploads

POST /upload — request a signed URL for uploading a file

Required body fields (per schema):

• file_type: MIME type (e.g., image/png, application/dxf, application/pdf, application/vnd.ms-excel, application/json, etc.)
• upload_process: one of the enumerated processes (e.g., floorplan, floorplan-location, rooms-data, people-data, occupancy-data, …)
• binding_id: a UUID that binds the upload to an entity (e.g., a location or process record)

const upload = await gospace.system.uploadFile({
  file_type: "application/dxf",
  upload_process: "floorplan",
  binding_id: "b51eadf5-e87b-49ec-a7bb-6e83152db660",
});

console.log(upload.data.signed_url); // PUT your file to this URL
console.log(upload.data.upload_id);  // Track this upload in your system

GET /upload — list upload records

const uploads = await gospace.system.getUploads();
console.log(uploads.data);

Pagination & Sorting

Most list endpoints support:

• skip — starting offset
• limit — number of items to return
• sort — field to sort by
• order — asc or desc

Example pattern:

const pageSize = 100;
let skip = 0;
const allPeople: any[] = [];

while (true) {
  const res = await gospace.directory.getPeople({ skip, limit: pageSize });
  allPeople.push(...res.data.people);
  if (res.data.people.length < pageSize) break;
  skip += pageSize;
}

Error Handling & Retries

Each method throws for non‑2xx responses. Wrap calls in try/catch:

try {
  const res = await gospace.directory.getTeams();
  console.log(res.data.teams);
} catch (err) {
  console.error("Failed to get teams:", err);
}

Simple retry helper:

async function withRetry<T>(fn: () => Promise<T>, attempts = 3): Promise<T> {
  let lastErr;
  for (let i = 0; i < attempts; i++) {
    try { return await fn(); } catch (err) { lastErr = err; }
  }
  throw lastErr;
}

const data = await withRetry(() =>
  gospace.directory.getPeople({ skip: 0, limit: 10 })
);

License

gospace AI API SDK License Agreement

Copyright (c) 2025 gospace AI

The @gospace-ai/api SDK is proprietary software provided by gospace AI. This software is licensed solely to pre‑registered, paying clients who have an active subscription or agreement with gospace AI. Usage of this software is strictly limited to authorized clients who have obtained a valid API key from gospace AI.

Terms of Use

1. Restricted Access — This SDK may only be used by pre‑registered, paying clients with a valid subscription or agreement with gospace AI. Unauthorized use, distribution, or modification of this software is strictly prohibited.
2. API Key — A valid API key, issued by gospace AI, is required to use the SDK and authenticate all API requests.
3. No Redistribution — You may not redistribute, sublicense, or share the SDK or its source code without explicit written permission from gospace AI.
4. No Warranty — The SDK is provided “as is,” without warranty of any kind, express or implied, including but not limited to warranties of merchantability, fitness for a particular purpose, or non‑infringement.
5. Termination — gospace AI reserves the right to terminate your access to the SDK if you violate this agreement or fail to maintain an active subscription.

To obtain a license or API key, contact gospace AI at [email protected] or visit:

• https://www.gospace.com
• https://docs.gospace.com
• https://developer.gospace.com

All rights not expressly granted herein are reserved by gospace AI.