API Reference

Complete reference for the Gigamemory REST API. All endpoints return JSON responses.

Base URL

https://api.gigamemory.ai/v1

Authentication

All API requests require your API key sent in the X-Memory-Key header. Generate your key from the dashboard.

X-Memory-Key: gm_key_xxxxxxxxxxxxxxxx

Rate Limits

Rate limits vary by plan. Standard limits are 100 requests per minute for Starter, 500 for Pro, 2,000 for Growth, and custom limits for Enterprise. Rate limit headers are returned with every response. See the Quick Start for the full breakdown.

POST /v1/episodes

Ingest a memory episode. Gigamemory automatically extracts entities and graph relationships from the provided text.

Request Body

Parameter	Type	Required	Description
text	string	required	The text containing information to remember
metadata	object	optional	Additional context (source, tags, timestamp, etc.)

Example Request

curl -X POST https://api.gigamemory.ai/v1/episodes \
  -H "X-Memory-Key: gm_key_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Acme Corp was founded in 2020 by Jane Smith. Jane is the CEO.",
    "metadata": {
      "source": "company_profile",
      "tags": ["leadership"]
    }
  }'

import requests

response = requests.post(
    "https://api.gigamemory.ai/v1/episodes",
    headers={
        "X-Memory-Key": "gm_key_xxxxxxxxxxxxxxxx",
        "Content-Type": "application/json"
    },
    json={
        "text": "Acme Corp was founded in 2020 by Jane Smith. Jane is the CEO.",
        "metadata": {
            "source": "company_profile",
            "tags": ["leadership"]
        }
    }
)

print(response.json())

const response = await fetch("https://api.gigamemory.ai/v1/episodes", {
  method: "POST",
  headers: {
    "X-Memory-Key": "gm_key_xxxxxxxxxxxxxxxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    text: "Acme Corp was founded in 2020 by Jane Smith. Jane is the CEO.",
    metadata: {
      source: "company_profile",
      tags: ["leadership"]
    }
  })
});

console.log(await response.json());

Example Response

{
  "id": "ep_abc123def",
  "entities_extracted": 2,
  "relationships_extracted": 1,
  "created_at": "2026-06-13T10:30:00Z"
}

POST /v1/search

Query the memory graph. Returns relevant entities, facts, and the graph relationships connecting them.

Request Body

Parameter	Type	Required	Description
query	string	required	Natural language query about entities and relationships
limit	integer	optional	Max results to return (default: 10, max: 50)
min_relevance	float	optional	Minimum relevance threshold (0.0 to 1.0)

Example Request

curl -X POST https://api.gigamemory.ai/v1/search \
  -H "X-Memory-Key: gm_key_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Tell me about Acme Corp and its leadership",
    "limit": 5
  }'

import requests

response = requests.post(
    "https://api.gigamemory.ai/v1/search",
    headers={
        "X-Memory-Key": "gm_key_xxxxxxxxxxxxxxxx",
        "Content-Type": "application/json"
    },
    json={
        "query": "Tell me about Acme Corp and its leadership",
        "limit": 5
    }
)

results = response.json()
for r in results["results"]:
    print(f"{r['entity']}: {r['fact']}")

const response = await fetch("https://api.gigamemory.ai/v1/search", {
  method: "POST",
  headers: {
    "X-Memory-Key": "gm_key_xxxxxxxxxxxxxxxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    query: "Tell me about Acme Corp and its leadership",
    limit: 5
  })
});

const results = await response.json();
console.log(results);

Example Response

{
  "results": [
    {
      "entity": "Acme Corp",
      "fact": "Acme Corp was founded in 2020 by Jane Smith",
      "relevance": 0.94
    },
    {
      "entity": "Jane Smith",
      "fact": "Jane Smith is CEO of Acme Corp",
      "relevance": 0.91
    }
  ],
  "graph": {
    "relationships": [
      { "source": "Jane Smith", "relation": "founded", "target": "Acme Corp" },
      { "source": "Jane Smith", "relation": "is CEO of", "target": "Acme Corp" }
    ]
  }
}

GET /v1/usage

Retrieve current usage statistics for your account — entity count, API calls, and limits.

Example Request

curl https://api.gigamemory.ai/v1/usage \
  -H "X-Memory-Key: gm_key_xxxxxxxxxxxxxxxx"

import requests

response = requests.get(
    "https://api.gigamemory.ai/v1/usage",
    headers={"X-Memory-Key": "gm_key_xxxxxxxxxxxxxxxx"}
)

print(response.json())

const response = await fetch("https://api.gigamemory.ai/v1/usage", {
  headers: {
    "X-Memory-Key": "gm_key_xxxxxxxxxxxxxxxx"
  }
});

console.log(await response.json());

Example Response

{
  "total_entities": 1247,
  "entity_limit": 10000,
  "api_calls_this_period": 3421,
  "period_reset": "2026-07-01T00:00:00Z"
}

GET /v1/export

Export all memories as plain Markdown files. Compatible with Obsidian and any markdown editor. No proprietary format.

Example Request

curl https://api.gigamemory.ai/v1/export \
  -H "X-Memory-Key: gm_key_xxxxxxxxxxxxxxxx" \
  -o memories.zip

import requests

response = requests.get(
    "https://api.gigamemory.ai/v1/export",
    headers={"X-Memory-Key": "gm_key_xxxxxxxxxxxxxxxx"}
)

with open("memories.zip", "wb") as f:
    f.write(response.content)

const response = await fetch("https://api.gigamemory.ai/v1/export", {
  headers: {
    "X-Memory-Key": "gm_key_xxxxxxxxxxxxxxxx"
  }
});

const blob = await response.blob();
const url = URL.createObjectURL(blob);
const a = document.createElement("a");
a.href = url;
a.download = "memories.zip";
a.click();

Response

Content-Type: application/zip
Content-Disposition: attachment; filename="memories_export.zip"

# Each .md file has frontmatter
---
entity: "Acme Corp"
source: "company_profile"
created_at: "2026-06-13T11:00:00Z"
---
# Acme Corp

Acme Corp was founded in 2020 by Jane Smith.

DELETE /v1/episodes/{id}

Delete a specific episode by ID. Removes the associated entities and graph relationships.

Example Request

curl -X DELETE https://api.gigamemory.ai/v1/episodes/ep_abc123def \
  -H "X-Memory-Key: gm_key_xxxxxxxxxxxxxxxx"

import requests

response = requests.delete(
    "https://api.gigamemory.ai/v1/episodes/ep_abc123def",
    headers={"X-Memory-Key": "gm_key_xxxxxxxxxxxxxxxx"}
)

print(response.json())

const response = await fetch(
  "https://api.gigamemory.ai/v1/episodes/ep_abc123def",
  {
    method: "DELETE",
    headers: {
      "X-Memory-Key": "gm_key_xxxxxxxxxxxxxxxx"
    }
  }
);

console.log(await response.json());

Example Response

{
  "id": "ep_abc123def",
  "status": "deleted",
  "deleted_at": "2026-06-13T11:30:00Z"
}

Error Codes

Status	Code	Description
400	bad_request	Invalid request body or missing required parameters
401	unauthorized	Missing or invalid API key
404	not_found	Episode not found
429	rate_limited	Too many requests — reduce your request rate or upgrade your plan
500	internal_error	Server error — our team has been notified

All errors return a consistent JSON body:

{
  "error": {
    "code": "not_found",
    "message": "Episode not found",
    "request_id": "req_abc123"
  }
}