> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memmachine.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API

> Examples for using MemMachine's REST API

## Hello World: A Guide to the MemMachine RESTful API v2

This guide provides a quick and simple way to get started with the MemMachine RESTful API v2 using `curl` commands.

### Prerequisites

Ensure your MemMachine server is running.

```bash theme={null}
memmachine-server
```

<Steps>
  <Step title="List Projects">
    Check for existing projects. This `POST` request returns a list of all projects available in your organization.

    **Command:**

    ```bash theme={null}
    curl -X POST "http://127.0.0.1:8080/api/v2/projects/list" \
    -H "Content-Type: application/json" \
    -d '{}'
    ```
  </Step>

  <Step title="Create a Project">
    Before adding memories, you must ensure a project exists.

    **Command:**

    ```bash theme={null}
    curl -X POST "http://127.0.0.1:8080/api/v2/projects" \
    -H "Content-Type: application/json" \
    -d '{
      "org_id": "my-org",
      "project_id": "my-first-project",
      "description": "A test project for REST API",
      "config": {
        "embedder": "my-openai-embedder",
        "reranker": "my-rrf-reranker"
      }
    }'
    ```
  </Step>

  <Step title="Add a New Memory">
    The `POST /api/v2/memories` endpoint allows you to add one or more messages to the system.

    **Command:**

    ```bash theme={null}
    curl -X POST "http://127.0.0.1:8080/api/v2/memories" \
    -H "Content-Type: application/json" \
    -d '{
      "org_id": "my-org",
      "project_id": "my-first-project",
      "messages": [
        {
          "content": "This is a simple test memory.",
          "producer": "user-alice",
          "produced_for": "agent-bob",
          "role": "user",
          "timestamp": "2025-11-24T10:00:00Z",
          "metadata": {
            "type": "fact",
            "topic": "testing"
          }
        }
      ]
    }'
    ```

    **Expected Output:**

    You will receive a JSON response containing the results of the operation.
  </Step>

  <Step title="Search for the Memory">
    Now let's find the memory we just added. The `POST /api/v2/memories/search` endpoint searches both episodic and semantic memory. Set `agent_mode` to `true` to use retrieval-agent search behavior.

    **Command:**

    ```bash theme={null}
    curl -X POST "http://127.0.0.1:8080/api/v2/memories/search" \
    -H "Content-Type: application/json" \
    -d '{
      "org_id": "my-org",
      "project_id": "my-first-project",
      "query": "simple test memory",
      "top_k": 5,
      "types": ["episodic", "semantic"],
      "agent_mode": true
    }'
    ```

    **Expected Output:**

    You should see a JSON response containing `episodic_memory` and `semantic_memory` results that match your query.
  </Step>

  <Step title="Delete Memories">
    To clean up, you can use the `POST /api/v2/memories/episodic/delete` endpoint to remove specific chronological events or message logs.

    **Command:**

    ```bash theme={null}
    curl -X POST "[http://127.0.0.1:8080/api/v2/memories/episodic/delete](http://127.0.0.1:8080/api/v2/memories/episodic/delete)" \
    -H "Content-Type: application/json" \
    -d '{
      "org_id": "my-org",
      "project_id": "my-first-project",
      "episodic_id": "specific-id-here",
      "episodic_ids": []
    }'
    ```

    You will also want to use the `POST /api/v2/memories/semantic/delete` endpoint to remove distilled facts, traits, or knowledge entries:

    ```
    curl -X POST "[http://127.0.0.1:8080/api/v2/memories/semantic/delete](http://127.0.0.1:8080/api/v2/memories/semantic/delete)" \
    -H "Content-Type: application/json" \
    -d '{
      "org_id": "my-org",
      "project_id": "my-first-project",
      "semantic_id": "specific-id-here",
      "semantic_ids": []
    }'
    </Step> </Steps>
        "producer": "user-alice"
      }
    }'
    ```
  </Step>
</Steps>