ViviScape.API.Open · v1 · stable

Build on the operating system for operations.

A REST API at api.viviscape.io, an MCP server that exposes your workspace to Claude and other AI clients, and a first-class vs CLI. Three integration paths, one platform.

# 1. Authenticate → access token
curl https://api.viviscape.io/api/v1/account/authenticate \
  -H "Content-Type: application/json" \
  -d '{ "username": "you@co.com", "password": "••••" }'

# 2. Call any endpoint with the returned access_token
curl https://api.viviscape.io/api/v1/companies/list \
  -H "Authorization: Bearer $ACCESS_TOKEN"

From zero to your first API call in 3 minutes.

1

Create a workspace

Sign up free at work.viviscape.io — no credit card.

2

Get credentials

Use your account username + password against /api/v1/account/authenticate to mint an access_token.

3

Pick your client

Raw HTTPS, the viviscape-mcp server for AI agents, or dotnet tool install -g ViviScape.CLI for the shell.

4

Call the API

Read companies, write notes, log time, query insights, manage prospects — all from one base URL.

ViviScape.API.Open · api.viviscape.io

Every endpoint lives under /api/v1. Authenticate once, then send Authorization: Bearer <access_token> on every subsequent call.

Swagger UI OpenAPI JSON

Account & Auth

POST/api/v1/account/authenticate

Authenticate a user with username and password and return an access token.

GET/api/v1/account/info

Account profile, plan, and entitlements for the bearer token's owner.

GET/api/v1/account/services/list

List billable services / activity types defined on the account.

GET/api/v1/account/users

List users (team members) in the workspace.

CRM — Prospects, Clients, Companies

GET/api/v1/companies/list

List companies with paging and filters.

POST/api/v1/companies/add

Create a new company (organization) record.

POST/api/v1/clients/add

Create a client contact and attach it to a company.

GET/api/v1/clients/by-email/{email}

Look up a client by email — handy for inbound flows.

POST/api/v1/prospects/add

Create a prospect (top-of-funnel lead) with tags and source.

POST/api/v1/prospects/query

Search prospects by name, stage, owner, follow-up date, or tag.

Delivery — Projects, Tasks, Time

GET/api/v1/projects/list

List projects. Use ?active=true for the active subset.

GET/api/v1/projects/{id}/tasks

List tasks attached to a project, with status and assignment.

POST/api/v1/tasks/add

Create a task on a project or milestone.

GET/api/v1/tasks/open

Tasks open to the current user across all projects.

POST/api/v1/timelogs/add

Log time against a task, project, or service.

PUT/api/v1/timelogs/{id}

Adjust a time entry — duration, billability, or memo.

Knowledge — Notes & Insights

POST/api/v1/notes/add

Add a new note attached to any record (client, project, task).

POST/api/v1/notes/featured/upload/{note_id}

Upload a featured file/asset to a note as multipart form data.

POST/api/v1/notes/query

Full-text + structured search across notes.

POST/api/v1/insights/ai/log/summary

Generate an AI summary of an activity log span; result is governed and auditable.

GET/api/v1/insights/hours/by-person

Aggregated hours per person across a date range and project set.

GET/api/v1/insights/hours/by-project

Aggregated hours per project — input for utilization and margin reports.

viviscape-mcp — your workspace, as tools for AI.

An MCP server that hands Claude (or any MCP client) typed access to ViviScape — CRM, projects, companies, tasks, time tracking, notes, and insights.

npmjs.com/package/viviscape-mcp About MCP

Install & run

No install required — run directly via npx, or install globally for repeatability:

# run on demand
npx viviscape-mcp

# or pin it globally
npm install -g viviscape-mcp

Configure your MCP client

Drop this into claude_desktop_config.json or .mcp.json:

{
  "mcpServers": {
    "viviscape": {
      "command": "npx",
      "args": ["-y", "viviscape-mcp"],
      "env": {
        "VIVISCAPE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Environment: VIVISCAPE_API_KEY (required) · VIVISCAPE_API_URL (optional, defaults to https://api.viviscape.io).

Tools exposed to your agent

The server registers typed tools across these domains. Every call routes to the ViviScape API and respects the API key's permissions.

Prospects

prospect_add, prospect_get, prospect_update, prospect_query, follow-ups, notes

Clients

client_add, client_get, client_get_by_email, clients_by_company

Companies

company_add, company_list, company_update

Projects

project_get, project_list, project_list_active, project_staff, project_tasks, projects_by_company

Tasks

task_add, task_get, task_update, tasks_open, tasks_pending, tasks_by_company, tasks_by_milestone

Time logs

timelog_add, timelog_update

Notes

note_add, note_get, note_update, note_remove, notes_mine, notes_query

Insights

hours by person / service / project, AI summary, person stats, time totals

Account

account_info, account_services, account_users

vs — your workspace from the shell.

A global .NET 8 tool with a gh auth login-style browser flow. Scripted, scoped, and audit-friendly — perfect for CI, ops, and one-off automations.

nuget.org/packages/ViviScape.CLI

Install

Requires the .NET 8 SDK (or newer).

# install globally
dotnet tool install -g ViviScape.CLI

# sign in — browser opens to work.viviscape.io
vs auth login

vs --help

# upgrade later
dotnet tool update -g ViviScape.CLI

If vs isn't found, ensure %USERPROFILE%\.dotnet\tools is on PATH and open a fresh terminal.

How auth works

Browser-based loopback flow — same pattern as gh auth login:

  1. vs auth login starts a local listener and opens work.viviscape.io/auth/cli/connect.
  2. The bridge page reads your WorkOS session and POSTs it back to the CLI.
  3. Credentials are stored in Windows Credential Manager (or ~/.viviscape/credentials.json on macOS/Linux, mode 600).

Override the host with VIVISCAPE_BASE_URL (defaults to https://work.viviscape.io).

Sample sessions

# list active companies as JSON, pipe through jq
$ vs companies list --format json | jq '.[].name'

# create a company
$ vs companies add --name "Beacon & Co." --tag enterprise

# open one in your browser
$ vs companies open cmp_4f81

Why a CLI?

  • Drop into CI pipelines for nightly automation
  • Pipe-friendly --format json on every command
  • Same identity as the web — every action audit-logged
  • Cross-platform: Windows, macOS, Linux

Built for the systems your business depends on.

Auth & identity

Bearer tokens minted via /account/authenticate. Same identity perimeter across web, CLI, and MCP.

Predictable behavior

OpenAPI-described surface. List endpoints support paging, filtering, and stable ordering.

Versioned + stable

Everything lives under /api/v1. Breaking changes move to a new major; v1 stays compatible.

Full audit trail

Every API, MCP, and CLI call lands in the same activity log — attributable by user, agent, or token.

AI-friendly

The MCP server hands typed tools to Claude. Insights endpoints expose AI-summarized rollups via REST.

Open by default

ViviScape.API.Open is the public contract — Swagger docs at api.viviscape.io/swagger.

Pick a path. Ship today.

REST for production systems. MCP for AI agents. CLI for scripts and ops. Same identity. Same audit trail.