Skip to content

Moraya Integration

Configure Moraya to upload images to Picora by pasting a single JSON configuration snippet.

Prerequisites

Configuration Steps

1. Open Moraya Preferences

In Moraya, go to Preferences → Image Upload → Custom Provider.

2. Paste the JSON Config

Copy and paste the following JSON configuration, replacing sk_live_YOUR_KEY with your actual API key:

{
  "name": "Picora",
  "url": "https://api.picora.me/v1/images",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer sk_live_YOUR_KEY"
  },
  "bodyType": "multipart",
  "fileField": "file",
  "responseUrlPath": "data.url"
}

3. Save and Test

Click Save, then drag an image onto the Moraya window to test the upload. The permanent URL will be returned and ready to copy.

Config Field Reference

FieldDescription
urlThe Picora upload endpoint
methodAlways POST for uploads
headers.AuthorizationYour API key in Bearer format
bodyTypeMust be multipart for file uploads
fileFieldThe form field name (file)
responseUrlPathJSON path to extract the URL from the response

Notes

  • The data.url path extracts the url field from the nested data object in Picora’s response
  • Each uploaded image gets a unique 11-character ID, e.g., https://media.picora.me/xK9mR2pQ7vB.webp
  • Images are permanently stored — URLs never expire

Test Connection (No Placeholder Upload)

Don’t upload a throwaway test image to verify your API key — it pollutes your library and counts against quotas. Instead, send a GET request to /v1/auth/verify:

Terminal window
curl -s https://api.picora.me/v1/auth/verify \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Expected response on success:

{
  "success": true,
  "data": {
    "valid": true,
    "userId": "V1StGXR8_Z5jdHi6B-myT",
    "plan": "pro",
    "authType": "apiKey",
    "apiKeyId": "k_F7hY3nP0xQ8zJ2vR5aW1"
  }
}
  • 200 with valid: true — credentials OK, no upload performed, no storage written
  • 401 — API key is invalid or has been revoked
  • Zero database overhead (data is read from middleware cache); safe to call on every client launch or config save

AI Assistant via MCP (v0.13.0+)

Moraya v0.35+ embeds an MCP (Model Context Protocol) bridge so the built-in AI assistant can directly upload, list and manage Picora media — same npm package (@picora/mcp-server) used by Claude Desktop / Cursor.

Enable

Settings → AI Assistant → toggle Picora MCP. The currently bound API Key is used automatically (no extra config).

When creating the API Key for Moraya, choose the read + write scope (no DELETE) to minimize AI accident potential. Moraya’s UI clearly surfaces the scope so you always see what the AI can do.

What it can do

The 8 tools (upload_image / upload_video / upload_audio / list_media / get_media / update_media / delete_media / get_usage) are available — typical usage:

“Upload all PNGs from this folder to Picora and replace markdown image paths with the cloud URLs.”

“I’m running low on storage — find my 5 biggest videos.”

For full tool reference, prompt templates, troubleshooting and privacy details, see AI Workflows → Moraya or MCP stdio integration.

Knowledge Base Sync (v0.17.0+)

Moraya v0.35.0+ can sync local knowledge bases directly to Picora’s KB namespace, preserving your directory structure and enabling incremental two-way sync.

How it works

  1. Bind a local KB to a Picora KB — in Moraya’s KB settings, link a local directory to a Picora KB ID (create the KB first at center.picora.me/kbs or via API)
  2. First sync — Moraya pulls the full manifest, diffs against local files, and pushes changes in a single batch
  3. Incremental sync — subsequent syncs use since to pull only changed entries; Moraya stores serverTime from each manifest response to avoid clock drift

Requirements

  • Moraya v0.35.0 or later
  • An API Key with read + write scope (no DELETE needed for sync-only use)
  • A Picora KB created in advance (one KB per local directory)

Enable in Moraya

Go to Settings → Knowledge Bases → Picora Sync, then for each local KB:

  1. Select the local directory
  2. Paste your Picora KB ID (from center.picora.me/kbs or GET /v1/kbs)
  3. Choose sync mode: manual / on-save / interval / startup+close

Conflict handling

When the same file is modified both locally and remotely before sync, Moraya shows a KbSyncConflictPanel with three options:

OptionResult
Keep localLocal version overwrites remote
Accept remoteRemote version replaces local
SkipFile left in conflict state until next sync

Server-side conflict reasons: REMOTE_NEWER, REMOTE_DELETED, BASE_MISSING, LOCAL_HASH_MISMATCH. See the KB API reference for details.

CLI / scripted sync

You can also sync without Moraya using the API directly:

Terminal window
# 1. Pull manifest
curl https://api.picora.me/v1/kbs/{kbId}/manifest \
  -H "Authorization: Bearer sk_live_..."


# 2. Push changes
curl -X POST https://api.picora.me/v1/kbs/{kbId}/sync \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"ops": [{"op":"upsert","relativePath":"README.md","content":"...","sourceHash":"...","baseUpdatedAt":null}]}'

See the multi-KB workflow guide for the full diff-and-sync pattern.