Graph API Reference

REST API for searching, exploring, and writing to your knowledge graph. All endpoints require authentication.

Base URL

API

https://api.groundstonelabs.com

Authentication

Include your API key in the Authorization header on every request:

Header

Authorization: Bearer gs_ak_your_api_key

Generate keys from Settings > API Keys. Each key is scoped to a single organization. You will need your org_id for all endpoints.

Endpoints

POST /org/{org_id}/search

Search your graph for items matching a text query. Returns ranked results using full-text search across names, titles, and content.

Request Body

Parameter	Type		Description
`q`	string	required	Search query text
`limit`	integer	optional	Max results to return (default: 20, max: 100)
`node_type`	string	optional	Filter by item type (e.g. "person", "company")
`entity`	string	optional	Filter by business entity

Example

curl

curl -X POST https://api.groundstonelabs.com/org/YOUR_ORG_ID/search \
  -H "Authorization: Bearer gs_ak_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"q": "quarterly revenue report", "limit": 10}'

Response

JSON

{
  "results": [
    {
      "id": "item_abc123",
      "name": "Q4 Revenue Report",
      "type": "document",
      "entity": "acme-corp",
      "score": 0.92,
      "properties": {
        "source": "gmail",
        "date": "2026-03-15"
      }
    }
  ],
  "count": 1,
  "query": "quarterly revenue report"
}

GET /org/{org_id}/entity/{item_id}

Retrieve full details for a specific item, including all its properties and direct relationships.

Path Parameters

Parameter	Type		Description
`org_id`	string	required	Your organization ID
`item_id`	string	required	The item's unique identifier

Example

curl

curl https://api.groundstonelabs.com/org/YOUR_ORG_ID/entity/item_abc123 \
  -H "Authorization: Bearer gs_ak_your_api_key"

Response

JSON

{
  "id": "item_abc123",
  "name": "Acme Corporation",
  "type": "company",
  "properties": {
    "domain": "acme.com",
    "source": "gmail",
    "first_seen": "2026-01-10"
  },
  "relationships": [
    {
      "direction": "outgoing",
      "type": "employs",
      "target_id": "person_456",
      "target_name": "Jane Smith"
    }
  ]
}

POST /org/{org_id}/traverse

Explore connections starting from a specific item. Returns all related items up to N hops away, revealing the relationship network.

Request Body

Parameter	Type		Description
`start_id`	string	required	Item ID to start traversal from
`depth`	integer	optional	How many hops to traverse (default: 2, max: 5)
`edge_types`	string	optional	Comma-separated relationship types to follow

Example

curl

curl -X POST https://api.groundstonelabs.com/org/YOUR_ORG_ID/traverse \
  -H "Authorization: Bearer gs_ak_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"start_id": "item_abc123", "depth": 2}'

Response

JSON

{
  "start": "item_abc123",
  "depth": 2,
  "items": [
    {
      "id": "person_456",
      "name": "Jane Smith",
      "type": "person",
      "hop": 1,
      "via": "employs"
    },
    {
      "id": "email_789",
      "name": "Re: Project Update",
      "type": "email",
      "hop": 2,
      "via": "sent"
    }
  ]
}

GET /org/{org_id}/timeline

Get a chronological activity feed for your organization or a specific business entity. Shows recent items sorted by date.

Query Parameters

Parameter	Type		Description
`days`	integer	optional	Lookback window in days (default: 30)
`limit`	integer	optional	Max items to return (default: 50)
`entity`	string	optional	Filter to a specific business entity

Example

curl

curl "https://api.groundstonelabs.com/org/YOUR_ORG_ID/timeline?days=7&limit=20" \
  -H "Authorization: Bearer gs_ak_your_api_key"

Response

JSON

{
  "timeline": [
    {
      "id": "email_901",
      "name": "Invoice #4521 - March",
      "type": "email",
      "date": "2026-04-02",
      "source": "gmail",
      "entity": "acme-corp"
    }
  ],
  "count": 1,
  "days": 7
}

POST /org/{org_id}/write

Write data back to your graph. Add new items, create connections between existing items, or correct properties. Confidence gating ensures data quality.

Request Body

Parameter	Type		Description
`action`	string	required	`add`, `connect`, or `correct`
`confidence`	float	required	Confidence score from 0 to 1
`data`	object	required	The payload (varies by action)

Confidence Gating

Score	Behavior
`>= 0.9`	Auto-merged into the graph immediately
`0.7 - 0.89`	Queued for human review
`< 0.7`	Rejected - not written

Example: Add an item

curl

curl -X POST https://api.groundstonelabs.com/org/YOUR_ORG_ID/write \
  -H "Authorization: Bearer gs_ak_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "add",
    "confidence": 0.95,
    "data": {
      "name": "New Project Alpha",
      "type": "project",
      "entity": "acme-corp",
      "properties": {
        "status": "active",
        "start_date": "2026-04-01"
      }
    }
  }'

Example: Connect two items

curl

curl -X POST https://api.groundstonelabs.com/org/YOUR_ORG_ID/write \
  -H "Authorization: Bearer gs_ak_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "connect",
    "confidence": 0.92,
    "data": {
      "from_id": "person_456",
      "to_id": "item_abc123",
      "relationship": "works_at"
    }
  }'

GET /org/{org_id}/stats

Get a summary of your graph, including total item counts, relationship counts, and breakdowns by type and source.

Example

curl

curl https://api.groundstonelabs.com/org/YOUR_ORG_ID/stats \
  -H "Authorization: Bearer gs_ak_your_api_key"

Response

JSON

{
  "total_items": 15420,
  "total_relationships": 28310,
  "by_type": {
    "person": 342,
    "company": 87,
    "email": 8921,
    "document": 2150
  },
  "by_source": {
    "gmail": 9200,
    "calendar": 1800,
    "quickbooks": 3420
  }
}

Error Handling

The API returns standard HTTP status codes:

Code	Meaning
`200`	Success
`400`	Bad request - check your parameters
`401`	Unauthorized - invalid or missing API key
`403`	Forbidden - key does not have access to this organization
`404`	Not found - item or organization does not exist
`429`	Rate limited - slow down requests
`500`	Server error - try again or contact support

Error responses include a JSON body:

JSON

{
  "detail": "Organization not found"
}

Groundstone Labs

Graph API Reference

Base URL

Authentication

Endpoints

Request Body

Example

Response

Path Parameters

Example

Response

Request Body

Example

Response

Query Parameters

Example

Response

Request Body

Confidence Gating

Example: Add an item

Example: Connect two items

Example

Response

Error Handling