Skip to content
Ubimemo
Create account

Integrations / HTTP API

API integration guide

Create, read, update and delete original memories through the HTTP API. Search your project and sync memory files using the same APIs as the Codex, WorkBuddy and Claude Code integrations.

Integration operations

The HTTP API supports creating, reading, updating and deleting memories. The shared connector exposes the four MCP tools below; direct updates and deletions use the HTTP examples later in this guide.

  • sync_memories → verify the identity and project, create an import manifest, upload changed files, inspect receipts and start processing.
  • search_memories → search originals with GET /api/lite/projects/:id/search.
  • read_memory → inspect document metadata, then use GET /api/lite/documents/:id/read with the returned revision and hash.
  • save_memory → explicitly save selected text with POST /api/lite/documents; keep one stable request_key for all retries of that save.

Connection and authentication

Use https://ubimemo.com as the origin. All endpoints in this guide begin with /api and send and receive JSON.

Sign in, open Settings → Account → API keys, and create a key. Keep it in your backend or desktop client’s secret storage. Send Authorization: Bearer <API_KEY>. API keys do not expire automatically. Revoke keys you no longer use.

Every JSON write needs Content-Type: application/json and X-Memory-Workspace: 1. Send {} when starting an import. X-Memory-Workspace is a request guard, not a credential.

Call from a backend or desktop client. Browser requests are same-origin only; keep API keys in private storage.

An account key can access projects authorized to its account. A project key from connector onboarding is restricted to its assigned project and cannot create another project. A 403 key_scope response means the operation needs a different credential.

API responses use scopes for the project list, scope for the selected project, and scope_id for a document’s project ID. The project-selection query parameter is also named scope. All refer to projects. Keep these exact field names and the existing /api/lite/... endpoint paths in your integration.

Project responses retain full_memory_enabled: false for older connectors. This is a compatibility field, not a project mode setting. The memory_settings response field has been removed; integrations must not require it.

Create, search and read

Examples use curl and Node.js 22 or later. Supply UBIMEMO_API_KEY through your secret store or private environment. Set UBIMEMO_PROJECT_ID to the chosen project id and UBIMEMO_REQUEST_KEY to a new UUID. Keep that UUID and the exact request body for retries; use a new UUID only for a new operation.

Inspect your connection
curl --fail-with-body https://ubimemo.com/api/bootstrap \
  -H "Authorization: Bearer $UBIMEMO_API_KEY"

Retrieve authorized projects from GET /api/bootstrap and choose your destination from scopes. All returned projects support original memories. Keep its id, then use GET /api/bootstrap?scope=<PROJECT_ID> to verify that project and its sources. To create a new project, use the request below with an account key.

Create a project
curl --fail-with-body https://ubimemo.com/api/lite/projects \
  -H "Authorization: Bearer $UBIMEMO_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'X-Memory-Workspace: 1' \
  --data '{"name":"API demo"}'

Run this as api-example.mjs. It connects to https://ubimemo.com, saves one synthetic note, searches for it, and reads the complete original using the returned revision and hash.

Node.js · complete request flow
const base = 'https://ubimemo.com';
const key = process.env.UBIMEMO_API_KEY;
const project = process.env.UBIMEMO_PROJECT_ID;
const requestKey = process.env.UBIMEMO_REQUEST_KEY;
if (!key || !project || !requestKey) {
  throw new Error('Set UBIMEMO_API_KEY, UBIMEMO_PROJECT_ID and UBIMEMO_REQUEST_KEY');
}

async function api(path, method = 'GET', body) {
  const response = await fetch(new URL(path, base), {
    method,
    redirect: 'error',
    headers: {
      Authorization: 'Bearer ' + key,
      ...(body === undefined ? {} : {
        'Content-Type': 'application/json',
        'X-Memory-Workspace': '1',
      }),
    },
    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
  });
  const text = await response.text();
  let result;
  try { result = JSON.parse(text); } catch {
    throw new Error('HTTP ' + response.status + ': non-JSON response');
  }
  if (!response.ok) {
    throw new Error('HTTP ' + response.status + ': ' + (result.code || result.error));
  }
  return result;
}

const saved = await api('/api/lite/documents', 'POST', {
  project_id: project,
  request_key: requestKey,
  text: 'Cedar demo: the notebook color is teal.',
  provenance: { origin: 'API integration example' },
});
console.log('Saved:', saved.document_id, saved.revision_id, saved.indexing);

const query = new URLSearchParams({ q: 'Cedar demo', limit: '20' });
const search = await api('/api/lite/projects/' + project + '/search?' + query);
console.log('Search coverage:', search.routes);
const hit = search.selected.find(item => item.document_id === saved.document_id);
if (!hit) throw new Error('Saved note is not on this search page; inspect coverage and pagination');
const metadata = await api('/api/lite/documents/' + hit.document_id);
if (metadata.scope_id !== project) throw new Error('Document is outside the configured project');

let offset = 0;
const parts = [];
do {
  const params = new URLSearchParams({
    revision_id: hit.revision_id,
    sha256: hit.sha256,
    start_offset: String(offset),
    max_chars: '6000',
  });
  const page = await api('/api/lite/documents/' + hit.document_id + '/read?' + params);
  parts.push(page.content);
  offset = page.next_offset;
} while (offset !== null);
const original = parts.join('');
console.log('Original:', original);
console.log('Source receipt:', {
  document_id: hit.document_id, revision_id: hit.revision_id, sha256: hit.sha256,
});

The save receipt includes document_id (stable original identity), revision_id (current state revision), content_hash, content_version_id, job_id and indexing. A saved original is not proof that semantic indexing has finished. Search reports keyword/semantic coverage in routes.

Search previews may be partial. Read document metadata first and check that its project ID (scope_id) matches your project. Use each hit’s document_id, revision_id and sha256 to read the source, then follow next_offset until null. Offsets are UTF-16 code units and end_offset is exclusive. If a read returns stale_document, search again before reading the changed source.

Update a memory

Use PATCH /api/lite/documents/:id to replace the complete memory text. Required JSON fields are request_key (a UUID for this update), expected_revision_id and text; provenance is optional. The stable document_id is preserved. Creates and updates share the 20,000 UTF-16 code unit text limit.

Try these examples on the synthetic note created above. Set UBIMEMO_DOCUMENT_ID to its document_id. Before a new update or delete, read its metadata below and verify that scope_id matches your project. Copy the returned revision_id into expected_revision_id; use the state revision, not content_version_id.

Read the current memory metadata
curl --silent --show-error --fail-with-body \
  "https://ubimemo.com/api/lite/documents/$UBIMEMO_DOCUMENT_ID" \
  -H "Authorization: Bearer $UBIMEMO_API_KEY"

Save this as update-memory.json. Replace the placeholders with a new UUID for this operation and the revision you reviewed; set text to the complete replacement. Save the target document ID and this exact file before sending. Every retry of this update must use the same target, UUID, expected revision and body.

update-memory.json · replace the placeholders
{
  "request_key": "<NEW_UPDATE_UUID>",
  "expected_revision_id": "<REVIEWED_REVISION_ID>",
  "text": "Cedar demo: the notebook color is amber.",
  "provenance": {
    "origin": "API integration example"
  }
}
Send or retry the saved update
curl --silent --show-error --fail-with-body \
  --request PATCH \
  "https://ubimemo.com/api/lite/documents/$UBIMEMO_DOCUMENT_ID" \
  -H "Authorization: Bearer $UBIMEMO_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'X-Memory-Workspace: 1' \
  --data-binary @update-memory.json

A successful update returns 200 with document_id, the accepted revision_id, content_hash, indexing and replayed. Use that revision and hash for subsequent reads, and the accepted revision for a later edit or delete. After a lost response, resend the saved update unchanged instead of fetching a new revision into its body.

Delete a memory

DELETE /api/lite/documents/:id permanently removes the original content, revision history and attribution, retaining a minimal deletion record. This cannot be undone through the API. It requires a JSON body with request_key and expected_revision_id, plus the same authentication and write headers as an update.

Keep UBIMEMO_DOCUMENT_ID set to the intended memory. Save the body below as delete-memory.json, using a new UUID distinct from the create/update keys and the current revision you reviewed. If you just updated the memory, use the update receipt’s revision_id. Keep this file unchanged for retries.

delete-memory.json · replace the placeholders
{
  "request_key": "<NEW_DELETE_UUID>",
  "expected_revision_id": "<REVIEWED_REVISION_ID>"
}
Send or retry the saved deletion
curl --silent --show-error --fail-with-body \
  --request DELETE \
  "https://ubimemo.com/api/lite/documents/$UBIMEMO_DOCUMENT_ID" \
  -H "Authorization: Bearer $UBIMEMO_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'X-Memory-Workspace: 1' \
  --data-binary @delete-memory.json

Success returns 200 with document_id, removed:true and replayed:false. If the response is lost, resend the same DELETE request and saved JSON body; a successful replay returns replayed:true. The original expected revision remains valid for that retry. Metadata and content reads return 404 after deletion, so do not make a fresh metadata read a prerequisite for retrying the saved deletion.

Sync memory files

Sync uploads only explicitly enrolled source files. With no sources configured, sync_memories returns no_sources without scanning files; search, read and explicit save remain available. See each client guide for supported source enrollment.

Create a manifest with POST /api/imports, mode:"source-only" and retain_source:true. Omit provider in new requests; imports retain originals without extraction. For the first file in a collection, send project_id and a source_name; retain the returned source_id and use it instead of project_id for later files. Hash the actual UTF-8 bytes with SHA-256 and record their byte length.

Inspect GET /api/imports/:id. If the file needs upload, send PUT /api/imports/:id/files with {path,data}, where data is base64 of the exact bytes. Read the receipt again and verify its project, source, path and hash, plus logical_document_id, revision_id and snapshot_available. Then send POST /api/imports/:id/start with {}. A 202 response accepts processing; inspect job status and search coverage for readiness.

Keep each accepted file’s hash and revision_id. Skip unchanged bytes. For a new path, send expected_revision_id:null; for changed bytes at an existing path, send that file’s last accepted revision. Persist the immutable request and bytes before uploading, and replay them after a transport failure. Missing local files leave the hosted originals in place.

Limits, pagination and errors

Search uses offset and limit (default 20, maximum 100) and returns total and has_more. The connector’s search_memories tool defaults to 5 results. Use next_offset to continue a source read.

Direct creates and updates: 20,000 UTF-16 code units within a 100 KiB JSON body. Reads: max_chars defaults to 6,000, maximum 12,000. Original-file imports support .md/.markdown/.txt, up to 10 MiB per file, 50 MiB per batch and 1,000 files. Manifests allow 2 MiB JSON; uploads allow base64 expansion plus 8 KiB. The connector applies its own smaller per-call file and time budgets.

Persist operation keys before sending. Retry a replay-safe write with the same key and identical payload after a transport failure. A 409 revision or idempotency conflict needs inspection and reconciliation; do not silently generate a new key or overwrite the newer revision. Project creation has no request_key, so inspect bootstrap before repeating a lost create response.

409 stale_document means the expected revision is no longer current: read and review the latest state before preparing a new operation with a new UUID. Do not automatically replace the revision in a pending request. 409 idempotency_conflict means a key was reused with different input: inspect the saved operation and recover its original body before retrying.

Hosted writes currently allow 120 requests per principal per minute. Guest identities have additional request, search and storage quotas. On 429, honor Retry-After when present and back off; it is not present on every limiter. Read code and error when available, and tolerate non-JSON gateway errors.

Common responses

  • 400 · Invalid JSON or fields. Correct the request.
  • 401 · Missing, expired or revoked authentication. Check the key.
  • 403 · Insufficient key permissions, missing write header or disallowed origin.
  • 404 · Missing or inaccessible source; withdrawn/deleted sources cannot be read as current.
  • 409 · Stale revision, reused key with changed input, changed bytes or upload required. Inspect code.
  • 429 · Rate or quota limit. Wait or follow the returned account action.
  • 503 · Provider or feature unavailable. Keyword search may still work when semantic search is unavailable.

Memory APIs

These 13 HTTP operations cover connection setup, memory CRUD, search and file sync. :id is a path parameter; replace it with the relevant project, document or import ID.

Hosted access

Memory operations accept an authorized account key or a project key for the configured destination. Creating a project requires an account key. Use the client setup guides for sign-in and onboarding.

Connection and project setup

Connection and project setup
EndpointPurpose and key inputs
GET/api/accountProject key / account keyVerify the current identity and key permissions before using the configured project.
GET/api/bootstrapProject key / account keyReturn authorized projects in scopes. Select a project with the scope query parameter; the response includes the selected scope and its sources.
POST/api/lite/projectsAccount key{name} → a project for original memories. Keep its id; requires an account key.

Memory CRUD and search

Memory CRUD and search
EndpointPurpose and key inputs
POST/api/lite/documentsProject key / account key{project_id, request_key, text, provenance?} → document_id, revision_id, content_hash, indexing.
GET/api/lite/projects/:id/searchProject key / account keyQuery q, offset, limit. Returns selected originals, exact read links and search coverage.
GET/api/lite/documents/:idProject key / account keyRead the project ID (scope_id), revision_id, content_hash and provenance. Verify the document belongs to the configured project before reading its text.
GET/api/lite/documents/:id/readProject key / account keyRequired revision_id and sha256; optional start_offset and max_chars. Returns content and next_offset.
PATCH/api/lite/documents/:idProject key / account key{request_key, expected_revision_id, text, provenance?}. Replace the complete text of an existing memory. Returns its stable document_id, accepted revision_id, content_hash, indexing and replayed.
DELETE/api/lite/documents/:idProject key / account keyJSON body {request_key, expected_revision_id}. Permanently delete the memory and its original history. Returns document_id, removed:true and replayed; identical retries reuse the saved body.

File sync

File sync
EndpointPurpose and key inputs
POST/api/importsProject key / account key{request_key, mode:"source-only", retain_source:true, files:[{path,sha256,bytes,expected_revision_id,provenance?}], project_id|source_id, source_name?}. Create a sync manifest; send exactly one destination and keep the returned id and source_id.
PUT/api/imports/:id/filesProject key / account key{path, data}; data is base64 of the exact UTF-8 bytes in the manifest.
POST/api/imports/:id/startProject key / account key{} → 202. Start processing after the original file is accepted. Inspect the job receipt and search coverage separately for processing and indexing readiness.
GET/api/imports/:idProject key / account keyInspect the sync receipt and file status. Check project_id, source_id, path, sha256, logical_document_id, revision_id, snapshot_available and needs_upload against the pending operation.