REST API

Auth and account#

Session endpoints used by the web app. They take no X-Workspace header. API keys cannot call them.

• POST/v1/auth/magic-linknone

  Request: {email, redirect_path?, invite_token?}

  Response: 202 {sent: true}. Never reveals whether an account exists.

• POST/v1/auth/verifynone

  Request: {token}

  Response: {user, csrf_token, redirect_path?, workspaces} and the session cookies. 400 invalid_token.

• GET/v1/auth/sessionsession

  Response: {user, csrf_token, workspaces}

• POST/v1/auth/signoutsession

  Response: 204. The session is revoked.

• GET/v1/mesession

  Response: {id, email, name?, created_at}

• PATCH/v1/mesession

  Request: {name?}

  Response: User

• DELETE/v1/mesession

  Request: {confirm_email}

  Response: 204. Deletes workspaces where you are the only member. 409 transfer_ownership_first if you are the only owner of a shared workspace.

Workspaces, members and keys#

• GET/v1/workspacessession

  Response: {data: Workspace[]} with your role

• POST/v1/workspacessession

  Request: {name, timezone?, default_currency?, sample?}

  Response: 201 Workspace. sample: true creates a sandbox with fictional data.

• GET/v1/workspaceread

  Response: Workspace + {you: {type, role?, scopes, agent_name?, key_prefix?}, limits}

• PATCH/v1/workspaceadmin

  Request: {name?, timezone?, default_currency?}

  Response: Workspace

• DELETE/v1/workspaceowner session

  Request: {confirm: "<slug>"}

  Response: 204. Everything is deleted at once. 422 confirmation_required on a mismatch.

• GET/v1/membersread

  Response: {data: Member[]}

• PATCH/v1/members/{user_id}owner session

  Request: {role}

  Response: Member. 409 last_owner.

• DELETE/v1/members/{user_id}owner session, or self

  Response: 204. 409 last_owner.

• GET/v1/invitesadmin

  Response: {data: Invite[]}

• POST/v1/invitesowner session

  Request: {email, role}

  Response: 201 Invite. 409 already_member.

• DELETE/v1/invites/{id}owner session

  Response: 204 (revoked)

• GET/v1/invites/lookup?token=none

  Response: {workspace_name, inviter_name?, email_hint, role, expired}

• POST/v1/invites/acceptsession

  Request: {token}

  Response: Workspace. 409 invite_mismatch.

• GET/v1/api-keysadmin

  Response: {data: ApiKey[]}

• POST/v1/api-keysowner session

  Request: {name, agent_name?, scopes, expires_at?}

  Response: 201 {api_key, secret: "rb_live_…"}. The secret is shown once.

• DELETE/v1/api-keys/{id}owner session

  Response: 204 (revoked)

Rounds#

{round} in a path is a round id or slug.

• GET/v1/rounds?status=open|closed|allread

  Response: {data: Round[]}, open rounds first

• POST/v1/roundswrite

  Request: {name, target_amount?, currency?, instrument?, valuation_cap?, pre_money_valuation?, target_close_on?, notes?, stages?}

  Response: 201 Round. 409 duplicate returns the existing round.

• GET/v1/rounds/{round}read

  Response: Round, with a count on each stage

• PATCH/v1/rounds/{round}write

  Request: Any round field, status

  Response: Round. Closing sets closed_on to today unless given.

• DELETE/v1/rounds/{round}admin

  Request: {confirm: "<name or slug>"}

  Response: 204

• PUT/v1/rounds/{round}/stageswrite

  Request: {stages: StageInput[], reassign?: {removed_key: target_key}}

  Response: Round. 409 stage_in_use, 422 invalid_stage_config.

• GET/v1/rounds/{round}/summaryread

  Response: RoundSummary

Investors in a round#

A participant is an investor in a round, addressed by investor_id. stage accepts a key or a label; an unknown one returns 422 stage_not_found with the valid keys.

• GET/v1/rounds/{round}/participantsread

  Request: q, stage, fit_min, type, tag, industry, follow_up=due|week|none, owner, sort, order, limit (≤1000), cursor

  Response: {data: Participant[], next_cursor, total}

• POST/v1/rounds/{round}/participantswrite

  Request: {investor_id, stage?, fit?, probability?, amount_soft?, next_step?, follow_up_on?, follow_up_note?, owner_user_id?}

  Response: 201 Participant, or 200 if already in the round (fields applied)

• POST/v1/rounds/{round}/participants/bulkwrite

  Request: {investor_ids (≤500), stage?}

  Response: {added, already}

• GET/v1/rounds/{round}/participants/{investor_id}read

  Response: Participant

• PATCH/v1/rounds/{round}/participants/{investor_id}write

  Request: {stage?, note?, fit?, probability?, amount_soft?, amount_committed?, committed_on?, follow_up_on?, follow_up_note?, next_step?, owner_user_id?}

  Response: Participant. One timeline entry per kind of change.

• POST/v1/rounds/{round}/participants/{investor_id}/stagewrite

  Request: {stage, note?}

  Response: {participant, changed, from, to}

• POST/v1/rounds/{round}/participants/{investor_id}/follow-upwrite

  Request: {on? | in_days? | clear?, note?}

  Response: {participant, changed}

• POST/v1/rounds/{round}/participants/{investor_id}/commitmentwrite

  Request: {amount, committed_on?, note?, move_to_won?}

  Response: {participant, previous_amount, moved_stage}

• DELETE/v1/rounds/{round}/participants/{investor_id}write

  Response: 204. Logged as removed_from_round.

• GET/v1/follow-ups?round=&within_days=0&include_overdue=true&limit=read

  Response: {today, data: FollowUpItem[], counts: {overdue, today, upcoming}}

Investors and activity#

• GET/v1/investorsread

  Request: q, type, tag, industry, round, not_in_round, sort, order, limit, cursor

  Response: {data: Investor[], next_cursor, total}

• POST/v1/investorswrite

  Request: Investor fields + on_duplicate?: return_existing | fill_empty | create_anyway

  Response: 201 {investor, created: true}, or 200 {investor, created: false, matched_on}

• GET/v1/investors/resolve?ref=read

  Response: {investor}. 404, or 409 ambiguous_reference (MCP reference rules).

• GET/v1/investors/{id}read

  Response: Investor, with rounds

• PATCH/v1/investors/{id}write

  Request: Investor fields + add_tags?, remove_tags?, append_notes?

  Response: Investor. 409 duplicate on an email or LinkedIn collision.

• DELETE/v1/investors/{id}write

  Response: 204. Hard delete, with their round entries and timeline.

• GET/v1/activitiesread

  Request: investor_id, round, kind, actor_type, since, until, limit, cursor

  Response: {data: Activity[], next_cursor}, newest first

• POST/v1/activitieswrite

  Request: {investor_id, kind: note|email|call|meeting, body, occurred_at?, round?, direction?, idempotency_key?}

  Response: 201 Activity, or 200 with duplicate: true on a repeated key

• DELETE/v1/activities/{id}write

  Response: 204. Notes, emails, calls and meetings only; 409 not_deletable otherwise.

Imports and exports#

• POST/v1/imports/previewwrite

  Request: ImportRequest

  Response: ImportPreview. Writes nothing.

• POST/v1/importswrite

  Request: ImportRequest

  Response: ImportResult. One transaction; error rows are skipped and reported.

• GET/v1/importsread

  Response: {data: ImportRun[]} (last 50)

• GET/v1/export?format=jsonread

  Response: The whole workspace as JSON

• GET/v1/investors/export?format=csvread

  Response: All investors as CSV

• GET/v1/rounds/{round}/export?format=csv|jsonread

  Response: One round as CSV or JSON