API Reference

Build on KinCo

A REST API for managing shared wealth data programmatically. Authenticate with a bearer token or API key, subscribe to webhooks, and integrate KinCo into your stack.

Get an API Key Browse Endpoints

Quick start

Get an API key

Generate a key from your account settings. Keys are prefixed kinco_ and shown once — store them securely.

Authenticate

Pass your key as a bearer token in every request: Authorization: Bearer kinco_…

Query your data

All endpoints live under https://api.kinco.io/api/v1. Responses follow a consistent JSON envelope.

Example request curl

curl https://api.kinco.io/api/v1/groups \
  -H "Authorization: Bearer kinco_your_key_here" \
  -H "Accept: application/json"

200 Response application/json

{
  "items": [
    {
      "id": "grp_01hx...",
      "name": "Dubai Villa Partnership",
      "base_currency": "AED",
      "created_at": "2024-09-01T10:00:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Endpoints

Base URL: https://api.kinco.io/api/v1

Groups

GET /api/v1/groups List all groups for the authenticated user

POST /api/v1/groups Create a new group (caller becomes admin)

GET /api/v1/groups/{id} Get group details with members

PATCH /api/v1/groups/{id} Update group name or base currency

DELETE /api/v1/groups/{id} Delete a group (owner only)

Assets

GET /api/v1/groups/{id}/assets List assets (filterable by type, searchable)

POST /api/v1/groups/{id}/assets Create an asset (real_estate, bank_account, investment_account, other)

GET /api/v1/groups/{id}/assets/{assetId} Get asset with latest valuation

PATCH /api/v1/groups/{id}/assets/{assetId} Update asset details

DELETE /api/v1/groups/{id}/assets/{assetId} Delete asset (admin only)

GET /api/v1/groups/{id}/assets/{assetId}/detail Full asset detail — valuations, transactions, ownership, liabilities, exit

Valuations

GET /api/v1/groups/{id}/assets/{assetId}/valuations List valuations (ordered by date desc)

POST /api/v1/groups/{id}/assets/{assetId}/valuations Add a new valuation (editor+)

PATCH /api/v1/groups/{id}/assets/{assetId}/valuations/{valId} Update a valuation

DELETE /api/v1/groups/{id}/assets/{assetId}/valuations/{valId} Delete a valuation

Asset Transactions

GET /api/v1/groups/{id}/assets/{assetId}/transactions List income and expense transactions for an asset

POST /api/v1/groups/{id}/assets/{assetId}/transactions Record a transaction (income or expense, with category)

PATCH /api/v1/groups/{id}/assets/{assetId}/transactions/{txId} Update a transaction

DELETE /api/v1/groups/{id}/assets/{assetId}/transactions/{txId} Delete a transaction

Asset Exits

GET /api/v1/groups/{id}/exits List all exited assets with realized returns in base currency

GET /api/v1/groups/{id}/assets/{assetId}/exit Get the exit record for an asset (404 if not yet exited)

POST /api/v1/groups/{id}/assets/{assetId}/exit Record an asset sale — computes net proceeds, CAGR, hold period, rent yield

DELETE /api/v1/groups/{id}/assets/{assetId}/exit Undo an exit (editor+)

Ledger

GET /api/v1/groups/{id}/ledger Unified ledger view with per-member breakdown

GET /api/v1/groups/{id}/contributions List contributions (filterable by asset, member, category)

POST /api/v1/groups/{id}/contributions Record a contribution

PATCH /api/v1/groups/{id}/contributions/{contribId} Update a contribution

DELETE /api/v1/groups/{id}/contributions/{contribId} Delete a contribution

GET /api/v1/groups/{id}/distributions List distributions

POST /api/v1/groups/{id}/distributions Record a distribution

PATCH /api/v1/groups/{id}/distributions/{distId} Update a distribution

DELETE /api/v1/groups/{id}/distributions/{distId} Delete a distribution

Liabilities

GET /api/v1/groups/{id}/liabilities List liabilities with remaining balance and payment history

POST /api/v1/groups/{id}/liabilities Create a liability (mortgage, loan, line of credit, other)

GET /api/v1/groups/{id}/liabilities/{liabId} Get a liability with all payments

PATCH /api/v1/groups/{id}/liabilities/{liabId} Update a liability

DELETE /api/v1/groups/{id}/liabilities/{liabId} Delete a liability

POST /api/v1/groups/{id}/liabilities/{liabId}/payments Record a payment against a liability

DELETE /api/v1/groups/{id}/liabilities/{liabId}/payments/{payId} Delete a payment

Metrics & Sheets

GET /api/v1/groups/{id}/metrics Portfolio metrics — active/exited assets, P&L, ownership, realized returns, performance

GET /api/v1/groups/{id}/metrics/assets/{assetId} Per-asset metrics — CAGR, ROI, equity, ownership breakdown

GET /api/v1/groups/{id}/metrics/monthly Yearly financial sheets — monthly P&L + balance sheet (optionally filtered by asset)

Ownership

GET /api/v1/groups/{id}/assets/{assetId}/ownership List ownership shares with member details

PATCH /api/v1/groups/{id}/assets/{assetId}/ownership Bulk update ownership percentages (auto or manual)

Members & Invitations

GET /api/v1/groups/{id}/members List group members and roles

PATCH /api/v1/groups/{id}/members/{memberId} Update member role (admin only)

DELETE /api/v1/groups/{id}/members/{memberId} Remove a member

GET /api/v1/groups/{id}/invitations List pending invitations for the group

POST /api/v1/groups/{id}/invitations Invite a new member by email

DELETE /api/v1/groups/{id}/invitations/{inviteId} Cancel a pending invitation

GET /api/v1/invitations/{token} Look up an invitation by token (unauthenticated)

POST /api/v1/invitations/accept Accept an invitation by token

Activity

GET /api/v1/groups/{id}/activity Paginated activity feed — all events for the group with actor, resource, and metadata

Documents

GET /api/v1/groups/{id}/documents List documents (filterable by asset, searchable by name)

POST /api/v1/groups/{id}/documents Upload a document (PDF, images, Office, CSV — max 10 MB)

DELETE /api/v1/groups/{id}/documents/{docId} Delete a document and its storage file

Webhooks

GET /api/v1/webhooks List registered webhooks

POST /api/v1/webhooks Register a webhook endpoint with event subscriptions

PATCH /api/v1/webhooks/{id} Update webhook URL, events, or active state

DELETE /api/v1/webhooks/{id} Delete a webhook

POST /api/v1/webhooks/{id}/test Send a test payload to verify your endpoint is reachable

API Keys

GET /api/v1/api-keys List your API keys (secrets are never returned after creation)

POST /api/v1/api-keys Create a new API key — returns the raw key once; store it securely

DELETE /api/v1/api-keys/{id} Revoke an API key immediately

User

GET /api/v1/users/me Get the authenticated user's profile

PATCH /api/v1/users/me Update display name or other profile fields

GET /api/v1/users/me/invitations List pending invitations addressed to the user's email

Authentication

API Key

Best for server-to-server integrations. Generate keys in your account settings — each key has configurable scopes and rate limits.

Authorization: Bearer kinco_…

User JWT

Best for client-side apps acting on behalf of a signed-in user. Pass the Supabase session token in the same header.

Authorization: Bearer eyJ…

Role-based access

admin

Full write access — manage members, invitations, roles, and group settings.

editor

Create and update assets, valuations, contributions, distributions, and documents.

viewer

Read-only access to all group data.

Webhooks

Register HTTPS endpoints to receive real-time event notifications. Every delivery includes an X-KinCo-Signature header (HMAC-SHA256) so you can verify authenticity.

Available events

group.createdgroup.updatedgroup.deletedasset.createdasset.updatedasset.deletedvaluation.createdvaluation.updatedvaluation.deletedcontribution.createdcontribution.deleteddistribution.createddistribution.deletedmember.addedmember.removedmember.role_updateddocument.uploadeddocument.deleted

Pagination

All list endpoints return a consistent envelope. Use limit and offset query params to paginate.

{
  "items":  [...],
  "total":  142,
  "limit":  50,
  "offset": 0,
  "has_more": true
}

Rate limits

Developer

60 req / min 1,000 req / month

Growth

500 req / min 100,000 req / month

Scale

2,000 req / min 1,000,000 req / month

Enterprise

Custom Unlimited

When a rate limit is exceeded the API returns 429 Too Many Requests with a Retry-After header.

Ready to integrate?

KinCo is in private beta. Join the waitlist to be among the first developers with API access.

Get Early API Access