Decile hub connector

Decile Hub Connector

Decile Hub is a VC fund-management + CRM platform. The Decile Hub API v1 is the first per-client custom connector in the Lossless tree: each VC client has its own Decile tenant (subdomain), its own API token, and its own clients/<slug>/.env. This skill is the operating guide for pulling from and pushing to that API, and for mapping its records into our SurrealDB canonical layer.

Source of truth. The authoritative contract is the on-disk OpenAPI 3.0.1 spec: ai-labs/augment-it/clients/humain-vc/inputs/decilehub/202506_decilehub-docs_swagger.yaml (11,970 lines). The full endpoint inventory lives in references/endpoint-inventory.md. When in doubt, read the spec — do not paraphrase Decile's API from memory.

When to use this skill

• Pulling data from Decile (list/get people, organizations, pipeline prospects, deals, funds, portfolio companies, …)
• Pushing data to Decile (create/upsert people & organizations, add prospects, append notes, create tasks, …)
• Wiring the Decile connector for a new client (new tenant subdomain + token in that client's .env)
• Building or maintaining the decile-mcp server (ai-labs/augment-it/services/decile-mcp/)
• Reconciling Decile records into SurrealDB persons / organizations

Connection contract

Thing	Value
Base URL	https://<tenant>.decilehub.com — per-tenant subdomain (humain-vc → https://humain.decilehub.com). All routes are under /api/v1/.
Auth	Authorization: <token> — the raw API token, no Bearer prefix (securitySchemes.api_key = type: apiKey, in: header, name: Authorization). One stale curl example in the docs shows Bearer — ignore it; the scheme is a raw apiKey header.
Token source	Generated in Hub at /settings/api. Legacy tokens are rejected with 403 — must be a current token.
Connection test	GET /api/v1/whoami — returns token kind (user/admin), the user, the account, account_user.roles, and accessible_pipeline_ids. Call this first to introspect capabilities.
Content type	application/json (except file upload/download, which is multipart/form-data / binary).

Env vars (live in the per-client .env)

Decile is tenant-scoped, so its config belongs in clients/<slug>/.env, resolved through the workspace connector seam (services/workspace/) — not in a shared root .env.

DECILE_API_URL=https://humain.decilehub.com      # the tenant's base URL
DECILE_HUB_API_KEY=<the API token from /settings/api>   # sent raw as the Authorization header

These are Decile's own naming. The earlier spec/README anticipated DECILE_API_BASE_URL / DECILE_API_KEY / DECILE_TENANT_ID; we standardize on the real names above and the tenant is encoded in the URL (no separate tenant id needed).

The canonical request shape

const res = await fetch(`${DECILE_API_URL}/api/v1/whoami`, {
  headers: { Authorization: DECILE_HUB_API_KEY, Accept: 'application/json' },
});

Pulling data (reads)

Reads are GET /api/v1/<resource> (list) and GET /api/v1/<resource>/{id} (show). Two cross-cutting concerns:

⚠️ There are THREE pagination patterns — do not assume one

The API is not uniform. Detect the pattern per endpoint group (see the inventory for which is which):

Pattern	Used by	Query params	Response envelope
A — offset, 0-indexed	Directory (people/organizations), events, files, tasks, variables, email_templates, account_users, financial_reports	page (0-indexed; fixed page size, usually 50/100; mostly no per_page)	{ data: [...], pagination: { total_count, current_page, total_pages } }
B — offset, 1-indexed	Firm-admin / accounting (entities, capital_accounts, journal_entries, accounting_accounts, capital_calls)	page (1-indexed, default 1), per_page (≤100, default 50)	{ <resource_key>: [...], page, per_page, total } — array key varies (entities, capital_accounts, …); no nested pagination
C — keyset / cursor	Newer agent-oriented (activity_entries, deals/shares, deal_memos, portfolio_companies, investments)	page_token (opaque, from prior response), per_page (≤100, default 25)	{ data: [...], pagination: { next_page_token, has_more } }
(D — Base community)	/base/*	page (1-indexed), per_page	{ items|posts|channels: [...], meta: { page, per_page, total, has_more } }

Filtering & custom data points

• Most list endpoints accept resource-specific filters (name, email, created_after, stage_name, …) — see the inventory.
• custom_data_points query param on people/organizations/pipeline_prospects list+show: * = all, comma-list = subset, empty = none. Select-type values resolve to human-readable labels on read; internal jsonb keys are never returned.
• include pulls associations (notes, people, organizations, referred_by, …); fields narrows the response.

Pushing data (writes)

Prefer the upsert endpoints — they're idempotent and map cleanly to our model

Endpoint	Natural key	Required fields	Response
POST /api/v1/person	email	first_name, last_name, email	201 { status, person_id, changes: { field: [old, new] } }
POST /api/v1/organization	name	name	201 { status, organization_id, changes }
POST /api/v1/pipeline_prospect	person email / org name	pipeline_id + prospect (exactly one of person|organization)	201 { status, pipeline_prospect_id, changes }
POST /api/v1/deals/share	organization_id	organization_id, company_name, the_bet, referring_manager_name, referring_manager_email	200 (updated) / 201 (created)

The singular upsert routes (/person, /organization, /pipeline_prospect — note: singular) match-or-create by natural key and return a changes diff. This is the right default for sync.

Bulk create = dedup, not upsert

POST /api/v1/people, /organizations, /pipeline_prospects (plural) process the first 100 and return { created, duplicates, errors }. Duplicates (by email / name) are skipped, not updated — use these for first-load, the singular upserts for ongoing sync.

Other common writes

• Notes: POST /api/v1/{people|organizations}/{id}/notes and /pipeline_prospects/{id}/notes — body { note: { body, context } }.
• Tags: tag_list (comma-separated string) adds; remove_tag_list removes (upsert routes only).
• Custom data points (write): the custom_data_points object in person/org/prospect bodies. New fields are defined via POST /api/v1/pipelines/{pipeline_id}/data_points (account admin; format enum incl. string, select, currency_us, url, …).
• Not idempotent: POST /entities and journal-entry creates re-create on retry — GET first to check.

Write fields — people & organizations

There is no standalone Person/Organization schema — stored fields are dynamic (data / custom_data_points jsonb). The documented write fields:

• Person: first_name, last_name, email*, middle_name, phone, linkedin, tag_list, custom_data_points, note, picture (base64/URL), address, referred_by, organizations: [{ name, title }].
• Organization: name*, website, description, tag_list, logo, custom_data_points, note, address, referred_by, people: [associated_person].

Errors

Canonical shape (used on most 4xx):

{ "error": { "code": "validation_failed", "message": "...", "field": null, "valid_values": null, "details": null } }

• Common codes: forbidden, bad_request, not_found, validation_failed, invalid_parameter, confirmation_required, unresolved_variables, already_finalized, …
• Inconsistency to handle: a few endpoints (e.g. single PATCH /pipeline_prospects/{id} on 400/404/422) return a bare { error: "string" } — the client must tolerate both shapes.
• No rate-limit headers and no webhooks are defined in the spec. Async jobs poll a status_url (e.g. financial reports); some actions return 202 (enqueued).

Mapping Decile → SurrealDB canonical layer

Decile is a per-client source; everything written into our canonical layer must carry the client tag (see [[Client-Tagging-on-Canonical-Writes]]). The natural mapping:

Decile	SurrealDB	Join key	Notes
Person	persons	email (Decile's natural key)	data / custom_data_points → person fields; organizations_with_titles → affiliation edges
Organization	organizations	name → slug (slugify)	data / custom_data_points → org fields; logo (attached_image) available
PipelineProspect	an observations-style relationship	pipeline_id + prospectable	stage / probability / rating are pipeline-scoped facts
PortfolioCompany	organizations (the underlying org) + investment facts	organization_id	fund×org pair; investment tranches are separate

Decile's upsert-by-natural-key + changes diff mirrors our own upsert discipline (SELECT-by-key → MERGE/CREATE). When syncing Decile → SurrealDB, treat Decile as one source and record provenance; do not let a Decile refresh overwrite operator-curated commentary. See the SurrealDB connection contract in [[Connecting-To-And-Using-SurrealDB]].

The two surfaces this skill backs

1. This skill — the operating guide (you're reading it).
2. The decile-mcp server — ai-labs/augment-it/services/decile-mcp/ (TypeScript): a typed client that resolves base URL + token from the per-client .env, normalizes the three pagination patterns and the error shape, and exposes Decile operations as MCP tools. The spec marks agent-facing operations with x-agent-tool: true — those are the tools to expose first. Register with claude mcp add -s project.

See also

• references/endpoint-inventory.md — the exhaustive endpoint list, grouped by tag
• The OpenAPI spec: ai-labs/augment-it/clients/humain-vc/inputs/decilehub/202506_decilehub-docs_swagger.yaml
• [[Connecting-To-And-Using-SurrealDB]] — the canonical-layer connection + client-tagging contract
• [[Workspaces-as-Tenant-Primitive]] — the per-client connector seam Decile plugs into
• [[Client-Tagging-on-Canonical-Writes]] — every canonical write carries its client