# API: Activity

| Method | Path | What it does | Scope |
|---|---|---|---|
| GET | `/v1/activities` | List activities, newest first (filters: record_id, type, source, external_id, from, to). Private items show only to their owner; metadata-only items hide their content. | `activities:read` |
| POST | `/v1/activities` | Post an activity (custom event) to records' timelines. Idempotent on (source, external_id); changed content becomes a new revision. | `activities:write` |
| GET | `/v1/activities/:id` | Get one activity with the records it's on | `activities:read` |
| GET | `/v1/activities/:id/revisions` | Earlier versions of an activity, newest first (kept when its source changed it) | `activities:read` |
| GET | `/v1/activities/:id/transcript` | A conversation's transcript: participants and speaker turns with times (ms from the start) | `transcripts:read` |
| DELETE | `/v1/activities/by-external-id` | Tell us the source deleted an event; it disappears from timelines (history keeps it). Connector sources can't be hidden this way. | `activities:write` |
| GET | `/v1/activities/schema` | JSON Schema for the activity create body | `activities:read` |
| POST | `/v1/meetings/:id/transcript` | Attach a transcript to a meeting: pasted, a link to the file, or a link to the recording to transcribe | `transcripts:write` |
| POST | `/v1/participants/resolve` | Match or create contacts (and accounts by business email domain) for email, calendar, Slack or notetaker participants. Teammates are recognized, never created as contacts. | `activities:write` |
| GET | `/v1/provenance/resolve` | Follow a provenance source_id (gmail:<id>, slack:<channel>:<ts>, google_calendar:<id>, an import id…) to the activity, import row or record behind it | `records:read` |
| GET | `/v1/transcription` | Whether this server can transcribe recordings | `transcripts:read` |
| POST | `/v1/transcripts` | Create a meeting (title, time, attendees) with its transcript | `transcripts:write` |

## Examples

### GET /v1/activities

List activities, newest first (filters: record_id, type, source, external_id, from, to). Private items show only to their owner; metadata-only items hide their content.

```bash
curl -s "https://api.closefinch.com/v1/activities" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/activities`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### POST /v1/activities

Post an activity (custom event) to records' timelines. Idempotent on (source, external_id); changed content becomes a new revision.

```bash
curl -s -X POST "https://api.closefinch.com/v1/activities" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'
```

```js
const res = await fetch(`https://api.closefinch.com/v1/activities`, {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();
```

### GET /v1/activities/$ID

Get one activity with the records it's on

```bash
curl -s "https://api.closefinch.com/v1/activities/$ID" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/activities/${id}`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### GET /v1/activities/$ID/revisions

Earlier versions of an activity, newest first (kept when its source changed it)

```bash
curl -s "https://api.closefinch.com/v1/activities/$ID/revisions" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/activities/${id}/revisions`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### GET /v1/activities/$ID/transcript

A conversation's transcript: participants and speaker turns with times (ms from the start)

```bash
curl -s "https://api.closefinch.com/v1/activities/$ID/transcript" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/activities/${id}/transcript`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### DELETE /v1/activities/by-external-id

Tell us the source deleted an event; it disappears from timelines (history keeps it). Connector sources can't be hidden this way.

```bash
curl -s -X DELETE "https://api.closefinch.com/v1/activities/by-external-id" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/activities/by-external-id`, {
  method: "DELETE",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### GET /v1/activities/schema

JSON Schema for the activity create body

```bash
curl -s "https://api.closefinch.com/v1/activities/schema" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/activities/schema`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### POST /v1/meetings/$ID/transcript

Attach a transcript to a meeting: pasted, a link to the file, or a link to the recording to transcribe

```bash
curl -s -X POST "https://api.closefinch.com/v1/meetings/$ID/transcript" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'
```

```js
const res = await fetch(`https://api.closefinch.com/v1/meetings/${id}/transcript`, {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();
```

### POST /v1/participants/resolve

Match or create contacts (and accounts by business email domain) for email, calendar, Slack or notetaker participants. Teammates are recognized, never created as contacts.

```bash
curl -s -X POST "https://api.closefinch.com/v1/participants/resolve" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'
```

```js
const res = await fetch(`https://api.closefinch.com/v1/participants/resolve`, {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();
```

### GET /v1/provenance/resolve

Follow a provenance source_id (gmail:<id>, slack:<channel>:<ts>, google_calendar:<id>, an import id…) to the activity, import row or record behind it

```bash
curl -s "https://api.closefinch.com/v1/provenance/resolve" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/provenance/resolve`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### GET /v1/transcription

Whether this server can transcribe recordings

```bash
curl -s "https://api.closefinch.com/v1/transcription" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/transcription`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### POST /v1/transcripts

Create a meeting (title, time, attendees) with its transcript

```bash
curl -s -X POST "https://api.closefinch.com/v1/transcripts" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'
```

```js
const res = await fetch(`https://api.closefinch.com/v1/transcripts`, {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();
```

Request and response schemas: [https://www.closefinch.com/openapi.json](https://www.closefinch.com/openapi.json). All resources: [API reference](https://www.closefinch.com/docs/api).