Quickstart
Create a mind and send the first two messages from a trusted backend.
Want to experience an evolving mind before integrating the API? Start with the CLI quickstart.
Before you begin
Create an API key in the Plural Matter Console, then save it in your server-side secret store.
export PLURALMATTER_API_KEY="mind_live_replace_me"Create a mind
curl https://api.pluralmatter.com/v1/minds \
--request POST \
--header "Authorization: Bearer $PLURALMATTER_API_KEY" \
--header "Content-Type: application/json" \
--data '{"name":"Support assistant"}'Save the returned id. A mind belongs to the same project as the API key that created it.
Send an experience
Every message is attributed to an actor. Use a stable actor ID derived from
your own authenticated user record. The project API key identifies your
application, but /v1/messages also requires a mind-scoped actor token. Issue
one from your trusted backend before sending the message:
export ACTOR_TOKEN=$(curl https://api.pluralmatter.com/v1/actor-tokens \
--request POST \
--header "Authorization: Bearer $PLURALMATTER_API_KEY" \
--header "Content-Type: application/json" \
--data '{"mind_id":"mind_example","actor_id":"user_123"}' \
| jq -r '.actor_token')Then include the returned token in the x-mind-actor-token header. Keep both
the project API key and actor token on your trusted backend; do not expose
either credential to a browser or mobile client.
curl https://api.pluralmatter.com/v1/messages \
--request POST \
--header "Authorization: Bearer $PLURALMATTER_API_KEY" \
--header "x-mind-actor-token: $ACTOR_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"mind_id": "mind_example",
"actor_id": "user_123",
"idempotency_key": "0195cfc0-dabe-7c6f-bb2f-971c749d929a",
"mind_consistency": "required",
"model": "sonnet",
"max_tokens": 256,
"messages": [
{"role": "user", "content": "I prefer concise weekly summaries."}
]
}'Use it later
Send another request with the same mind_id and actor_id, obtaining an
actor token for that actor and mind as above:
{
"mind_id": "mind_example",
"actor_id": "user_123",
"mind_consistency": "required",
"model": "sonnet",
"max_tokens": 256,
"messages": [
{ "role": "user", "content": "How should you format my update?" }
]
}For production requests, generate a new idempotency key for each logical non-streaming operation and retry with the same key when the outcome is uncertain.