# Together API

> Together lets a small circle of people see when they've crossed paths on the
> same companies, decks, and founder profiles. This API lets you check in at a
> URL programmatically and get back who in your network has been at the same
> place — for wiring Together into your own dealflow or CRM.

## Base URL

https://together.brdg.app/api/v1

## Auth

Every request needs one header: `Authorization: Bearer <key>`, where `<key>` is
your Bridge API key (the identity layer behind Together). No cookies, no extra
keys. Get a key from your Bridge account.

Check that a key works:

```
curl -H "Authorization: Bearer $KEY" https://together.brdg.app/api/v1/healthz
```

A 200 with your user id means you're set.

## Check in at a URL, get network matches

`POST /api/v1/checkins/match`

Records a check-in for you at the target behind the URL (marked `source=api`),
then returns the people in your network who have also been at the same target,
with their notes and tags. The URL is classified just like the extension — a
company (registrable domain), a LinkedIn profile, or an artifact on a recognised
platform (DocSend, Google Docs, Figma, GitHub, …) — with query params stripped.

```
curl -X POST https://together.brdg.app/api/v1/checkins/match \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://stripe.com/pricing"}'
```

Optional body fields: `comment` (string), `tags` (string[]), `category`
(string), `target_title` (string), `limit` (1–100, default 50). `target_kind` +
`target_key` is an advanced override; untrackable URLs (search pages, internal
surfaces) return 400.

Response shape:

```
{
  "checkin":  { ...the check-in we recorded for you, "source": "api" },
  "deduped":  false,                       // true if folded into your existing 24h row
  "target":   { "kind": "company", "key": "stripe.com", "key_hash": "…", "host": null, "integration": null },
  "matches":  [ { ...check-in row, "participant": { "display_name", "username", "avatar_url" } } ],
  "meta":     { "match_count": 1 }
}
```

## Check whether a target is already in your CRM

`GET /api/v1/crm/check`

Read-only — records nothing. Reports whether you have a CRM connected (Attio
today) and, when you pass a target, whether that company or person is already in
it. A missing CRM is a normal 200 result (`configured: false`), NOT an error — so
you can branch on connection state without parsing an error envelope. Pass a
`url` (classified server-side, same as `/checkins/match`) or a pre-classified
`target_kind` + `target_key`. Omit the target for a pure "is a CRM connected?"
probe. Artifacts (docs, decks) aren't tracked by CRMs → `in_crm: false`.

```
curl -H "Authorization: Bearer $KEY" \
  "https://together.brdg.app/api/v1/crm/check?url=https://stripe.com"
```

Response shape:

```
{
  "configured": true,                        // false when no CRM is connected
  "provider":   "attio",                     // null when not configured
  "target":     { "kind": "company", "key": "stripe.com" },  // null when no target given
  "in_crm":     true,                        // does the target already exist in the CRM?
  "matches":    [ { "id", "name", "url", "lists": [ { "id", "name", "url" } ] } ]
}
```

## Watch a target — and manage your watchlist

`GET / POST / DELETE /api/v1/watchlist`

Your watchlist is a standing subscription: when anyone in your circle checks in
on or notes a watched company/person, you get a Together-bot DM. Private to you.
Add by URL (classified + hashed server-side — no need to compute a hash):

```
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://stripe.com"}' \
  "https://together.brdg.app/api/v1/watchlist"
```

→ `201` (now watching) or `200` (already watching): `{ "watch": { "id", ... }, "created": true }`.

List (newest first, `limit`/`offset` paging), then unwatch by the row's `id`:

```
curl -H "Authorization: Bearer $KEY" "https://together.brdg.app/api/v1/watchlist?limit=20"
curl -X DELETE -H "Authorization: Bearer $KEY" "https://together.brdg.app/api/v1/watchlist/<id>"
```

Delete is a soft unwatch (`{ "ok": true }`) — a later note-auto-watch won't
re-add a dismissed target. First-party clients may POST a pre-hashed
`target_kind` + `target_key_hash` instead of `url`.

## List your activity timeline

`GET /api/v1/activity`

The feed-shaped view that powers the app's Activity page — your circle's activity,
newest first, scoped to you and your accepted friends. A row appears when a
check-in carries intent (a comment or tags) or has a visible note attached (your own
+ friends' public notes). Each row is a check-in enriched with note metadata
(`note_count`, `note_preview`, `note_latest_at`, …).

```
curl -H "Authorization: Bearer $KEY" \
  "https://together.brdg.app/api/v1/activity?limit=20&tag=dealflow"
```

Query params (all optional): `q` (free-text search across check-in comment / target /
host, author name + username, and note body), `start` / `end` / `since` (ISO 8601),
`target_kind` (`company` | `person` | `artifact`), `target_key_hash`, `tag`
(repeatable — a row must contain ALL provided tags), `limit` (1–100, default 50),
`offset`.

Response shape:

```
{
  "data": [ { ...check-in row, "note_count": 2, "note_preview": "met the CEO at…" } ],
  "meta": { "total": 47, "limit": 20, "offset": 0 }
}
```

## Machine-readable spec

OpenAPI 3.1: https://together.brdg.app/api/v1/openapi.json

## Full docs

- Human guide: https://together.brdg.app/developers
- Quickstart: https://together.brdg.app/docs/api-quickstart.md
- Errors: https://together.brdg.app/docs/api-errors.md
(Endpoint reference is the OpenAPI spec linked above.)

## Good to know

- The URL is classified the same way in the API and the extension, so a check-in
  on `linkedin.com/in/jane` or a `docsend.com/view/<code>` deck matches a friend
  who hit the same profile or deck in-product. `docs.stripe.com` and
  `www.stripe.com` both resolve to the company `stripe.com`.
- Visibility is enforced on the server. You only ever see check-ins from people
  you've both added — never strangers.
- Repeated check-ins at the same target within 24h dedupe into one row
  (`deduped: true`) instead of piling up duplicates.