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//.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](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://.decilehub.com — per-tenant subdomain (humain-vc → https://humain.decilehub.com). All routes are under /api/v1/. | | Auth | Authorization: — 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//.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=   # 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/ (list) and GET /api/v1//{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, emailtemplates, accountusers, financialreports | 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, capitalaccounts, journalentries, accountingaccounts, capitalcalls) | page (1-indexed, default 1), per_page (≤100, default 50) | { : [...], page, per_page, total } — array key varies (entities, capital_accounts, …); no nested pagination | | C — keyset / cursor | Newer agent-oriented (activityentries, deals/shares, dealmemos, portfoliocompanies, 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](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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: lossless-group
• Source: lossless-group/lossless-agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.