Quickstart

Four requests to your first search.

Every endpoint is a JSON POST with a bearer token, and errors are RFC 9457 Problem Details. Set PRIMITIVES_URL to your cell’s URL; the examples default to the local stack.

API reference

Step 1

Get an API key

Create a key on your company’s API keys page. It is shown once; keep it on your backend. Check it by asking which tenant it belongs to.

Credential: API key

POST /v1/tenant

export PRIMITIVES_API_KEY=prim_sk_…

curl -X POST ${PRIMITIVES_URL:-http://localhost:8080}/v1/tenant \
  -H "Authorization: Bearer $PRIMITIVES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

# {"tenant_id":"…"}

Step 2

Check a permission

Ask whether a signed-in user may do something to a resource. Use their session token from signing in. Resource types and roles come from your Access model; these examples use a `matter` type with a `view` permission, a `viewer` role and `title` searchable. A member of the customer organization the resource belongs to registers it and grants a role, then the check passes.

Credential: User session

POST /v1/permissions/check

export MATTER_ID=6f1c2b9e-0d4a-4f3e-9a51-2c7d8e9f0a1b

curl -X POST ${PRIMITIVES_URL:-http://localhost:8080}/v1/resources \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"resource_type":"matter","resource_id":"'"$MATTER_ID"'","organization_id":"'"$ORG_ID"'"}'

curl -X POST ${PRIMITIVES_URL:-http://localhost:8080}/v1/grants \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"resource_type":"matter","role":"viewer","user_id":"'"$USER_ID"'","resource_id":"'"$MATTER_ID"'"}'

curl -X POST ${PRIMITIVES_URL:-http://localhost:8080}/v1/permissions/check \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"resource_type":"matter","resource_id":"'"$MATTER_ID"'","permission":"view"}'

# {"allowed":true}

Step 3

Publish an event

Tell Primitives what happened to a resource. Events feed your audit trail, notification rules and search, delivered at least once.

Credential: API key

POST /v1/events

curl -X POST ${PRIMITIVES_URL:-http://localhost:8080}/v1/events \
  -H "Authorization: Bearer $PRIMITIVES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "matter.created",
    "subject": "'"$MATTER_ID"'",
    "actor_id": "'"$USER_ID"'",
    "data": {"title": "Indemnity review"}
  }'

# 202 {"id":"…"}

Step 4

Search

Find resources by the fields their type indexes, limited to those the user may see. Indexing is asynchronous, so a new event can take a moment to match.

Credential: API key

POST /v1/search

curl -X POST ${PRIMITIVES_URL:-http://localhost:8080}/v1/search \
  -H "Authorization: Bearer $PRIMITIVES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource_type": "matter",
    "query": "indemnity",
    "user_id": "'"$USER_ID"'",
    "permission": "view"
  }'

# [{"id":"6f1c2b9e-…","fields":{"title":"Indemnity review"}}]