> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Topo API Reference

> Explore the Topo REST API — sync contacts, manage exclusions, control sequences, read activities, and subscribe to webhooks from your own systems.

The Topo API is a REST API that lets you integrate your tools and workflows directly with your Topo workspace. Every resource is available over HTTPS, every request and response body is JSON, and every list response follows the same paginated envelope so you always know what to expect.

<Warning>
  **The Topo API is in pre-release and not stable yet.** While the surface is being finalized, breaking changes — renamed fields, changed parameters, or restructured endpoints — may still ship inside `/v1` without a version bump. Expect to update your integration as the API evolves. The versioning rules below describe the stability guarantees that take effect once the API reaches general availability.
</Warning>

## Base URL

All endpoints are served under a single versioned base URL:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
https://api.topo.io/v1
```

## What you can do

* **Sync contacts & accounts** — upsert contacts by email or LinkedIn URL, query your roster, and manage custom variables on contacts and accounts.
* **Manage exclusions** — add or remove contact and company suppression rules.
* **Control sequences** — enroll contacts, pause or stop runs, and remove list entries that sourced a sequence.
* **Read activities and messages** — pull outreach events and message content.
* **Manage contact & account lists** — create and populate segmentation lists.
* **Subscribe to webhooks** — register endpoints to receive real-time event payloads.
* **Manage tasks** — list, create, execute, complete, and reassign outreach tasks and standalone to-dos.
* **Push first-party events** — send your own product and website signals into Topo.

## Versioning

The major API version lives in the URL path (`/v1`). Topo follows these rules to keep your integration stable:

| Change type                                                                           | Ships as                                                 |
| ------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| New endpoint, new optional field, new response field, new enum value                  | Additive change in `/v1` — no action needed on your side |
| Removed or renamed endpoint, field, or scope; changed field type; changed HTTP status | Breaking change, ships as `/v2`                          |

You should write your client to **ignore unknown fields** in responses. Topo may add new fields to any response object at any time within `/v1`.

## Quick start

Once you have an API key (see [Authentication](/api-reference/authentication)), make your first request to confirm your credentials and see which scopes your key carries:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://api.topo.io/v1/me \
  -H "Authorization: Bearer topo_xxxxxxxxxxxx"
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "018f1a2b-3c4d-7e8f-9a0b-1c2d3e4f5a6b",
  "organization_id": "018e9d8c-7b6a-7f5e-4d3c-2b1a0f9e8d7c",
  "name": "My Integration Key",
  "key_prefix": "topo_xxxx",
  "scopes": ["contacts:read", "sequences:read"],
  "created_at": "2024-11-01T09:00:00Z",
  "last_used_at": "2025-01-15T14:23:11Z"
}
```

## Explore the docs

<CardGroup cols={2}>
  <Card title="Concepts" icon="book-open" href="/api-reference/concepts">
    Meet every object the API exposes and find the endpoint group that covers it.
  </Card>

  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Learn how to create API keys, pass them in requests, and scope them to least-privilege access.
  </Card>

  <Card title="Pagination & Filtering" icon="list" href="/api-reference/pagination-filtering">
    Understand the standard list envelope, page through large result sets, and filter records.
  </Card>

  <Card title="Errors & Rate Limits" icon="triangle-alert" href="/api-reference/errors-rate-limits">
    Decode error responses, handle rate limiting gracefully, and debug with request IDs.
  </Card>

  <Card title="Contacts" icon="contact-round" href="/api-reference/contacts">
    Read contacts in your workspace and manage their custom variables.
  </Card>

  <Card title="Events" icon="signal" href="/api-reference/events">
    Push first-party events so they become scored buying signals on the right contact.
  </Card>
</CardGroup>