internalai-agent/.agents/skills/contactdb/SKILL.md

name, description, user-invocable

name	description	user-invocable
contactdb	ContactDB REST API reference. Use when resolving people to contact_ids, searching contacts by name/email, or accessing relationships, notes, and platform identities.	false

ContactDB API Reference

ContactDB is the people directory. It stores contacts, their platform identities, relationships, notes, and links. Every person across all data sources resolves to a single ContactDB contact_id.

Base URL: http://localhost:42000/contactdb-api (via Caddy) or http://localhost:42800 (direct)

Core Entities

Contact

The central entity — represents a person.

Field	Type	Description
id	int	Unique contact ID
name	string	Display name
emails	EmailField[]	{type, value, preferred}
phones	PhoneField[]	{type, value, preferred}
bio	string?	Short biography
avatar_url	string?	Profile image URL
personal_info	PersonalInfo	Birthday, partner, children, role, company, location, how_we_met
interests	string[]	Topics of interest
values	string[]	Personal values
tags	string[]	User-assigned tags
profile_description	string?	Extended description
is_placeholder	bool	Auto-created stub (not yet fully resolved)
is_service_account	bool	Non-human account (bot, no-reply)
stats	ContactStats	Interaction statistics (see below)
enrichment_data	dict	Data from enrichment providers
platform_identities	PlatformIdentity[]	Identities on various platforms
created_at	datetime	When created
updated_at	datetime	Last modified
merged_into_id	int?	If merged, target contact ID
deleted_at	datetime?	Soft-delete timestamp

ContactStats

Field	Type	Description
total_messages	int	Total messages across platforms
platforms_count	int	Number of platforms active on
last_interaction_at	string?	ISO datetime of last interaction
interaction_count_30d	int	Interactions in last 30 days
interaction_count_90d	int	Interactions in last 90 days
hotness	HotnessScore?	Composite engagement score (0-100)

PlatformIdentity

Links a contact to a specific platform account.

Field	Type	Description
id	int	Identity record ID
contact_id	int	Parent contact
source	string	Data provenance (e.g., dataindex_zulip)
platform	string	Platform name (e.g., email, zulip)
platform_user_id	string	User ID on that platform
display_name	string?	Name shown on that platform
avatar_url	string?	Platform-specific avatar
bio	string?	Platform-specific bio
extra_data	dict	Additional platform-specific data
first_seen_at	datetime	When first observed
last_seen_at	datetime	When last observed

Relationship

Tracks connections between contacts.

Field	Type	Description
id	int	Relationship ID
from_contact_id	int	Source contact
to_contact_id	int	Target contact
relationship_type	string	Type (e.g., "colleague", "client")
since_date	date?	When relationship started
relationship_metadata	dict	Additional metadata

Note

Free-text notes attached to a contact.

Field	Type	Description
id	int	Note ID
contact_id	int	Parent contact
content	string	Note text
created_by	string	Who wrote it
created_at	datetime	When created

Link

External URLs associated with a contact.

Field	Type	Description
id	int	Link ID
contact_id	int	Parent contact
type	string	Link type (e.g., "github", "linkedin")
label	string	Display label
url	string	URL

REST Endpoints

GET /api/contacts — List/search contacts

Primary way to find contacts. Returns {contacts: [...], total, limit, offset}.

Query parameters:

Parameter	Type	Description
search	string?	Search in name and bio
is_placeholder	bool?	Filter by placeholder status
is_service_account	bool?	Filter by service account status
sort_by	string?	"hotness", "name", or "updated_at"
min_hotness	float?	Minimum hotness score (0-100)
max_hotness	float?	Maximum hotness score (0-100)
platforms	string[]?	Contacts with ALL specified platforms (AND)
last_interaction_from	string?	ISO datetime lower bound
last_interaction_to	string?	ISO datetime upper bound
limit	int	Max results (1-100, default 50)
offset	int	Pagination offset (default 0)

GET /api/contacts/me — Get self contact

Returns the platform operator's own contact record. Call this first in most workflows to get your own contact_id.

GET /api/contacts/{id} — Get contact by ID

Get full details for a single contact by numeric ID.

GET /api/contacts/by-email/{email} — Get contact by email

Look up a contact by email address.

Other Endpoints

Method	Path	Description
POST	/api/contacts	Create contact
PUT	/api/contacts/{id}	Update contact
DELETE	/api/contacts/{id}	Delete contact
POST	/api/contacts/merge	Merge two contacts
GET	/api/contacts/{id}/relationships	List relationships
GET	/api/contacts/{id}/notes	List notes
GET	/api/contacts/{id}/links	List links
GET	/api/platform-identities/contacts/{id}	List platform identities

Usage Pattern

1. Start with GET /api/contacts/me to get the operator's contact ID
2. Search by name with GET /api/contacts?search=Alice
3. Use contact IDs from results as filters in DataIndex queries (contact_ids parameter)
4. Paginate large result sets with offset increments