REST API & Agentic Ingress (MCP)

Developer Reference DEV-API-01

Managed by CultureOS

ToFF Attunement exposes a comprehensive REST API and a native Model Context Protocol (MCP) interface. This enables automated batch ingress, programmatic research synthesis, and autonomous agent queries.

Integration endpoints and API gateways are configured, deployed, and managed by CultureOS.

Authentication

All programmatic API requests must include an institutional API key passed in the HTTP Authorization header:

Authorization: Bearer <INSTITUTIONAL_API_KEY>

API tokens are generated via the Administrator Profile settings panel within https://listen.tomoffinland.org.

REST API Specifications

1. Ingesting a Web URL

Creates a new record and triggers the automated crawling, OCR, and indexing pipeline.

curl -X POST "https://listen.tomoffinland.org/api/v1/bookmarks" \
  -H "Authorization: Bearer $TOFF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "link",
    "url": "https://example.org/article-feature",
    "tags": ["press", "exhibition"]
  }'

2. Searching Ingested Records Programmatically

Executes a structured search against the MeiliSearch index using the standard query syntax.

curl -X GET "https://listen.tomoffinland.org/api/v1/bookmarks?q=tag:press%20is:fav&limit=20" \
  -H "Authorization: Bearer $TOFF_API_KEY"

3. Creating Curatorial Lists

Organizes related community discourse and reviews into formal dossiers.

curl -X POST "https://listen.tomoffinland.org/api/v1/lists" \
  -H "Authorization: Bearer $TOFF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "2026 European Tour Press Coverage",
    "description": "Comprehensive compilation of critical reviews and public feedback across European dates."
  }'

Model Context Protocol (MCP) Integration

ToFF Attunement supports direct integration with AI reasoning agents (including Claude Desktop, Antigravity, and custom Foundation research assistants) via the Model Context Protocol.

This capability allows an AI research agent to synthesize months of public commentary and press coverage on demand without manual export.

Claude Desktop Configuration

Add the following definition to claude_desktop_config.json:

{
  "mcpServers": {
    "toff-attunement": {
      "command": "npx",
      "args": ["-y", "@karakeep/mcp"],
      "env": {
        "KARAKEEP_API_ADDR": "https://listen.tomoffinland.org",
        "KARAKEEP_API_KEY": "YOUR_INSTITUTIONAL_API_KEY"
      }
    }
  }
}

Supported Agent Capabilities

• search-bookmarks: Semantic and keyword search across all indexed public records.
• get-bookmark-content: Direct extraction of raw sanitized article text for analysis.
• create-bookmark: Autonomous ingestion of newly discovered literature by background agents.
• get-lists / add-bookmark-to-list: Automated curation and classification into Foundation dossiers.