Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Response Format

All LocusGraph API responses are returned as JSON.

Endpoint Response Shapes

Store Event

{
  "event_id": "locus_abc123",
  "status": "recorded",
  "relevance": "high"
}
  • status — "recorded" or "filtered".
  • relevance — "high", "medium", or "low".

Retrieve Memories

{
  "memories": "Formatted memory text with relevant knowledge...",
  "items_found": 5
}
  • memories — Formatted text with matching knowledge.
  • items_found — Total number of matching items.

Generate Insights

{
  "insight": "Synthesized finding from your wisdom graph.",
  "recommendation": "Actionable suggestion based on the insight",
  "confidence": "high"
}
  • confidence — "high", "medium", or "low".

List Contexts

All list endpoints return paginated results:

{
  "context_types": [...],
  "total": 57,
  "page": 0,
  "page_size": 100
}

Use page and page_size query parameters to paginate.

Error Responses

Errors return a JSON object with an error field:

{
  "error": "Invalid graph_id parameter"
}

Error Codes

StatusMeaning
400Bad request. Invalid parameters or payload exceeds 256KB.
401Unauthorized. Missing or invalid agent-secret.
404Not found. The requested context does not exist.
429Rate limited. Back off and retry.
500Internal server error.

A 429 response means you are being rate limited. Use exponential backoff before retrying.

SDK Error Handling

Each SDK surfaces errors in an idiomatic way.

TypeScript

try {
  const result = await locus.storeEvent({ ... });
} catch (err) {
  // Throws Error with the API error message
  console.error(err.message);
}

Python

try:
    result = locus.store_event(...)
except RuntimeError as e:
    # Raises RuntimeError with the API error message
    print(str(e))

Rust

match client.store_event(params).await {
    Ok(result) => println!("{}", result.event_id),
    Err(e) => eprintln!("API error: {}", e),
}

The Rust SDK returns Result<T, LocusError>, letting you handle errors with standard pattern matching.

Related

Store Event
Error Handling Guide