REST API

A plain JSON HTTP API. Any language, no SDK required.

Base URL	https://api.venkai.fr
Auth	Authorization: Bearer vk_live_…
Content type	application/json
OpenAPI	/openapi.json — generated from the running app
Interactive docs	/docs

The OpenAPI document is the machine-readable source of truth; this documentation is the human-readable one. When they disagree, the OpenAPI document is right.

The two calls that matter

# write
curl -sX POST https://api.venkai.fr/api/memory \
  -H "Authorization: Bearer $VENKAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"project_id":"billing-service","agent_id":"planner",
       "type":"decision","importance":0.9,
       "content":"We use Postgres, not MongoDB, because the ranking query needs joins."}'

# read
curl -sG https://api.venkai.fr/api/context/billing-service/relevant \
  -H "Authorization: Bearer $VENKAI_API_KEY" \
  --data-urlencode 'query=which database did we pick' \
  --data-urlencode 'limit=5'

Everything else is management.

Other languages

TypeScriptGoPython (no SDK)

const BASE = "https://api.venkai.fr";
const H = {
  "Authorization": `Bearer ${process.env.VENKAI_API_KEY}`,
  "Content-Type": "application/json",
};

export async function remember(projectId: string, content: string, type = "fact", importance = 0.5) {
  const r = await fetch(`${BASE}/api/memory`, {
    method: "POST",
    headers: H,
    body: JSON.stringify({ project_id: projectId, agent_id: "ts-agent", content, type, importance }),
  });
  if (!r.ok) throw new Error(`venkai remember failed: ${r.status} ${await r.text()}`);
  return r.json();
}

export async function recall(projectId: string, query: string, limit = 5) {
  const u = new URL(`${BASE}/api/context/${projectId}/relevant`);
  u.searchParams.set("query", query);
  u.searchParams.set("limit", String(limit));
  const r = await fetch(u, { headers: H });
  if (!r.ok) throw new Error(`venkai recall failed: ${r.status} ${await r.text()}`);
  return (await r.json()).memories as Array<{ content: string; type: string; score: number }>;
}

package venkai

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "net/url"
    "os"
)

const base = "https://api.venkai.fr"

func do(req *http.Request, out any) error {
    req.Header.Set("Authorization", "Bearer "+os.Getenv("VENKAI_API_KEY"))
    req.Header.Set("Content-Type", "application/json")
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return err
    }
    defer resp.Body.Close()
    if resp.StatusCode >= 300 {
        return fmt.Errorf("venkai: %s", resp.Status)
    }
    return json.NewDecoder(resp.Body).Decode(out)
}

func Remember(project, content, typ string, importance float64) (map[string]any, error) {
    body, _ := json.Marshal(map[string]any{
        "project_id": project, "agent_id": "go-agent",
        "content": content, "type": typ, "importance": importance,
    })
    req, _ := http.NewRequest("POST", base+"/api/memory", bytes.NewReader(body))
    var out map[string]any
    return out, do(req, &out)
}

func Recall(project, query string, limit int) ([]map[string]any, error) {
    u, _ := url.Parse(fmt.Sprintf("%s/api/context/%s/relevant", base, project))
    q := u.Query()
    q.Set("query", query)
    q.Set("limit", fmt.Sprint(limit))
    u.RawQuery = q.Encode()
    req, _ := http.NewRequest("GET", u.String(), nil)
    var out struct {
        Memories []map[string]any `json:"memories"`
    }
    err := do(req, &out)
    return out.Memories, err
}

import os, requests

BASE = "https://api.venkai.fr"
H = {"Authorization": f"Bearer {os.environ['VENKAI_API_KEY']}"}

def remember(project, content, type="fact", importance=0.5, agent="py-agent"):
    r = requests.post(f"{BASE}/api/memory", headers=H, timeout=10, json={
        "project_id": project, "agent_id": agent,
        "content": content, "type": type, "importance": importance,
    })
    r.raise_for_status()
    return r.json()

def recall(project, query, limit=5):
    r = requests.get(f"{BASE}/api/context/{project}/relevant",
                     headers=H, params={"query": query, "limit": limit}, timeout=10)
    r.raise_for_status()
    return r.json()["memories"]

Conventions

• Timestamps are Unix epoch seconds as floats, not ISO strings.
• Project paths take your project key, not the internal proj_… id.
• Errors are {"detail": "..."}, FastAPI-style. See Errors.
• Rate limits apply only in production: 300 req/min authenticated, 60 req/min anonymous, per IP. 429 carries Retry-After.
• CORS is restricted to VENKAI_ALLOWED_ORIGINS. Browser calls from an unlisted origin are blocked — and note that shipping an API key to a browser exposes it, so server-side is the intended pattern.

Generating a client

curl -s https://api.venkai.fr/openapi.json -o venkai-openapi.json
npx @openapitools/openapi-generator-cli generate \
  -i venkai-openapi.json -g typescript-fetch -o ./venkai-client

Full endpoint reference: API Reference.