Agent API and MCP

Create a workspace-scoped key from Developer settings. The complete key is shown once, while Loresta stores only its SHA-256 hash. Follow the quickstart for a complete first request.

Endpoints

Method	Path	Purpose
GET	/api/v1/agent/persona	Read approved voice, facts, phrases, and offers
GET	/api/v1/agent/usage	Read the current usage period and privacy-minimal totals
POST	/api/v1/agent/draft	Classify one inbound message and prepare a grounded reply decision
POST	/api/v1/agent/handoff	Queue an existing conversation for creator review with explicit confirmation
POST	/mcp	Use Loresta through MCP streamable HTTP with scope-limited tool visibility

REST authentication

curl "https://loresta.co/api/v1/agent/persona?profileId=cr_example" \
  -H "Authorization: Bearer $LORESTA_AGENT_KEY"

The endpoint requires a valid active profileId from the same workspace as the key. The v1 public API does not list creator profiles.

Write request headers

Authorization: Bearer $LORESTA_AGENT_KEY
Content-Type: application/json
Idempotency-Key: one-unique-request-id

Available scopes

• persona:read
• usage:read
• replies:write
• handoffs:write

Start read-only whenever the integration does not need to prepare a write action.

Draft response

{
  "ok": true,
  "decision": {
    "intent": "offer_question",
    "riskLevel": "safe",
    "confidence": 0.94,
    "reply": "The editing guide is available from my creator Page.",
    "rationale": "Uses an approved offer fact.",
    "requiresCreator": false,
    "mediaAssetId": ""
  }
}

riskLevel is safe, review, or blocked. Do not send or publish a reply when requiresCreator is true. The API itself never sends a social message.

Conversation-aware drafting

When conversationId is supplied, Loresta loads up to 40 tenant-scoped messages and the available relationship context for that Loresta conversation. When it is omitted, callers may supply up to 40 history items with a maximum body length of 700 characters each.

The inbound message must contain 2 to 800 characters. The request body must be JSON and is limited to 32 KiB for REST drafting.

Handoff response

POST /api/v1/agent/handoff works only with an existing Loresta conversation that has an inbound message. The payload must contain confirm: true. A successful response sets the conversation to awaiting_owner and queues one creator notification.

{
  "ok": true,
  "conversationId": "cvs_example",
  "state": "awaiting_owner",
  "creatorNotified": true
}

See errors and limits for retry behavior and MCP server for the equivalent tools.