Contacts

Contacts and conversation infrastructure

Contacts API

Protected core TRI1 routes

Contacts routes reuse the existing TRI1 application service layer and keep private key material out of the API boundary.

GET	`/api/tri/contacts`	Fetch contacts available to the authenticated TRI1 service context. Scope: `contacts:read` or `contacts:write`
POST	`/api/tri/contacts/upsert`	Create or update contact metadata. Scope: `contacts:write`
POST	`/api/tri/read`	Update read state. Scope: `identity:read`
GET	`/api/tri/conversation-profile`	Fetch conversation profile data. Scope: `identity:read`
POST	`/api/tri/conversation-settings`	Update conversation settings. Scope: `identity:read`
POST	`/api/tri/conversation-state`	Update conversation state. Scope: `identity:write`

A key created with the dashboard Contacts preset carries only contacts:read and contacts:write; the read-state and conversation routes above additionally need the listed identity scopes, otherwise the API returns 403 insufficient_scope with the required scopes in the response.

Owner binding

Developer API keys act only on the developer's own TRI1 identity. Omit ownerTriId and the API fills in the identity your key is registered to; if you send an owner field it must match that identity or the request fails with 403 tri_core_owner_forbidden (this includes owner objects carrying someone else's public keys). A key whose developer account has no TRI1 identity gets 403 developer_identity_required. Environment service tokens and admin:tokens keys are exempt.

cURL

curl -H "Authorization: Bearer $TRI_API_SERVICE_TOKEN" \
  https://api.tri1space.com/api/tri/contacts

JavaScript fetch

const response = await fetch('https://api.tri1space.com/api/tri/contacts', {
  headers: {
    'X-TRI1-API-Key': process.env.TRI_API_SERVICE_TOKEN
  }
});

const contacts = await response.json();

Upsert contact

The owner is taken from your API key (see owner binding above). Pass the contact as flat fields, or as a contact object when you have a full public profile to store.

curl -X POST https://api.tri1space.com/api/tri/contacts/upsert \
  -H "Authorization: Bearer $TRI_API_SERVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "contactTriId": "tri1qcontact",
    "displayName": "Public Contact",
    "trusted": true
  }'

await fetch('https://api.tri1space.com/api/tri/contacts/upsert', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TRI_API_SERVICE_TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    contactTriId: 'tri1qcontact',
    displayName: 'Public Contact',
    trusted: true
  })
});

A successful upsert responds with created: true on first insert and emits a contact.created webhook; later upserts of the same contact emit contact.updated.