API Reference

Overview

The GrooveOS API lets you integrate team memory into your own applications, scripts, and agents. Read and write memory items, search your team's knowledge, and manage conversations — all programmatically.

Base URL: https://api.grooveos.app

Authentication

# All requests need:
Authorization: Bearer {your-api-token}
X-Team-Scope: {your-team-slug}

Quick start

# Test your token
curl https://api.grooveos.app/v1/me \
  -H "Authorization: Bearer $TOKEN"

# Search team memory
curl "https://api.grooveos.app/v1/memory/search?q=Q2+target" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Team-Scope: your-team"

Core endpoints

Health

GET /v1/healthz — No auth required. Returns {"status": "ok"} when the API is up.

Your profile

GET /v1/me — Returns your user info and team memberships. Useful for verifying your token and resolving your team slug.

Search memory

GET /v1/memory/search?q={query} — Semantic search across your team's memory. Results are ranked by relevance and filtered to your team scope automatically.

curl "https://api.grooveos.app/v1/memory/search?q=fundraising+target&truth_level_min=WORKING&limit=5" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Team-Scope: your-team"

Write a memory item

POST /v1/memory/upsert — Save a fact to your team's memory. If an item with the same content and source already exists, it is updated rather than duplicated.

curl -X POST https://api.grooveos.app/v1/memory/upsert \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Team-Scope: your-team" \
  -H "Content-Type: application/json" \
  -d '{
    "item": {
      "content": "The Q2 fundraising target is 2M€",
      "team_scope": "your-team",
      "project_scope": "fundraising",
      "visibility": "team",
      "confidence": 0.9,
      "truth_level": "WORKING",
      "source": "api:my-script",
      "validation_status": "pending"
    }
  }'
# Returns: {"id": "mem_abc123..."}

Get a memory item

GET /v1/memory/{item_id} — Retrieve a specific item by its ID. Returns the full item including all tagging fields, timestamps, and audit history.

Conversations

GET /v1/conversations — List your team's conversations, ordered by most recent. Paginate with ?limit= and ?offset=.

POST /v1/conversations — Create a conversation record manually (useful for importing conversations from external tools).

GET /v1/conversations/{id} — Get a specific conversation including all messages and extracted memory items.

Graph neighbors

GET /v1/graph/neighbors?entity={name} — Get entities related to a person, project, or concept in your team's knowledge graph. Useful for exploring connections without writing Cypher queries.

curl "https://api.grooveos.app/v1/graph/neighbors?entity=Alice" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Team-Scope: your-team"
# Returns people, projects, and concepts connected to Alice

System prompt

GET /v1/system-prompt — Get your team's CANONICAL facts formatted and ready for LLM injection. Use this as the system prompt in your own AI integrations so your models always know your team's ground truth.

curl https://api.grooveos.app/v1/system-prompt \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Team-Scope: your-team"
# Returns: "Team knowledge:\n- Q2 target: 2M€\n- Tech lead: Alice..."

Error codes

Rate limits

SDKs

Official SDKs are coming soon. For now, use the REST API directly with curl, requests (Python), or fetch (JavaScript).

Python example

import requests

def search_memory(query: str, team: str, token: str):
    response = requests.get(
        "https://api.grooveos.app/v1/memory/search",
        params={"q": query, "truth_level_min": "WORKING"},
        headers={
            "Authorization": f"Bearer {token}",
            "X-Team-Scope": team
        }
    )
    return response.json()

results = search_memory("Q2 target", "your-team", "your-token")

JavaScript example

async function searchMemory(query, team, token) {
  const params = new URLSearchParams({ q: query, truth_level_min: "WORKING" });
  const res = await fetch(
    `https://api.grooveos.app/v1/memory/search?${params}`,
    {
      headers: {
        "Authorization": `Bearer ${token}`,
        "X-Team-Scope": team
      }
    }
  );
  return res.json();
}

const results = await searchMemory("Q2 target", "your-team", "your-token");

What's next

• Memory & Knowledge — Understand truth levels and how memory promotion works.
• Teams & Projects — Manage team slugs, projects, and member roles.
• Plans & Billing — Compare rate limits and API access across plans.