API Reference Overview - Negentro Docs

The PiyAPI REST API provides programmatic access to persistent memory and context operations, allowing applications and agents to create, retrieve, search, update, and manage memory through standard HTTP requests. API VERSION: v1 BASE URL: Configure in your deployment

Quick start Get your API key and make your first memory request in a few minutes.

Quick Start Guide

Add Memories

Store information and context from your application’s conversations or events.

Search Memories

Retrieve relevant memories using semantic or contextual search.

Get Memories

Retrieve a specific stored memory when you already know its identifier.

curl -X POST "https://<your-piyapi-endpoint>/v1/memories" \
  -H "Authorization: Bearer $PIYAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "user_123", "content": "User prefers concise explanations"}'

Core Operations

METHOD	ENDPOINT	DESCRIPTION
POST	`/v1/memories`	Add Memories - Store new memories from conversations and interactions.
POST	`/v1/memories/search`	Search Memories - Find relevant memories using semantic search and filters.
PATCH	`/v1/memories/:id`	Update Memory - Modify existing memory content or metadata.
DELETE	`/v1/memories/:id`	Delete Memory - Remove a specific memory or perform supported deletion operations.

API Categories

Explore the API by functionality.

Memory APIs

Core memory operations including create, search, update, delete, history, and export workflows.

Events APIs

Track and inspect asynchronous memory-related events.

Entities APIs

Manage users, agents, applications, and associated memory data.

Organizations & Projects

Manage organization-level access, projects, and collaboration boundaries.

Webhooks

Receive real-time notifications for supported memory and system events.

Building a multi-tenant application? Learn how Organizations & Projects can be used to separate access, resources, and collaboration boundaries.

Authentication

All requests to the PiyAPI API must include a valid API key passed via the Authorization header using the Bearer scheme. Requests without a valid key will be rejected.

Header
Authorization: Bearer <PIYAPI_API_KEY>

API keys should be stored server-side.
Requests should be made through secure server-side environments.
Do not expose secrets in client-side code.

const response = await fetch(
  "https://<your-piyapi-endpoint>/v1/memories",
  { headers: { Authorization: `Bearer ${process.env.PIYAPI_API_KEY}` } }
)

Your application sends an HTTP request to the PiyAPI API (Memory / Context Layer), which returns a JSON response.

Keep your API key secure. Never expose API credentials in client-side code or public repositories. Use environment variables and server-side requests.

Next Steps

Add your first memory

Start storing persistent context through the API.

Search with filters

Learn advanced search and filtering techniques.

Build with cookbooks

See complete API workflows inside practical projects.

​Quick Start Guide

​Core Operations

​API Categories

Memory APIs

Events APIs

Entities APIs

Organizations & Projects

Webhooks

​Authentication

​Next Steps

Add your first memory

Search with filters

Build with cookbooks

Quick Start Guide

Core Operations

API Categories

Authentication

Next Steps