Attio SDK

⚠️ Experimental: This package is in active development and not ready for production use. APIs and features may change without notice.

A TypeScript SDK for interacting with the Attio REST API.

Features

• CLI for generating TypeScript SDK from Attio schema
• Fetch-based HTTP client
• Type-safe API requests and responses
• Object, Attribute, Record, List, List Entry, Note, Task, standard objects and custom objects fetchers
• Webhooks support

Usage

First, install the SDK and its peer dependencies:

pnpm add @spotable/attio-sdk

To generate the SDK from your Attio schema, run the following command. You can use the --help flag to see all available options for the generate command. Ensure that your Attio API key is provided via the ATTIO_API_KEY environment variable.

:warning: Keep your API key secure. Never hardcode it in your source code or expose it publicly. Always add your configuration file to .gitignore to prevent accidental commits.

attio-sdk generate --output ./output-directory --standard-types

Import and initialize the client:

import { AttioClient } from './output-directory';

const client = new AttioClient({ apiKey: 'YOUR_API_KEY' });

// Example: Fetch all objects
const objects = await client.objects.getAll();

Fetchers

The Attio SDK provides fetchers for interacting with different resources in the Attio API. Each fetcher exposes methods for creating, reading, updating, and deleting entities, as well as querying and subscribing to webhook events.

• client.objects — Manage Attio objects (standard and custom)
• client.attributes — Manage attributes for objects and lists
• client.records — Manage records for objects
• client.lists — Manage lists
• client.listEntries — Manage entries within lists
• client.notes — Manage notes attached to records or objects
• client.tasks — Manage tasks
• client.<OBJECT_SLUG> — Access custom objects using their slug (e.g., client.companies)
• client.webhooks — Manage and subscribe to webhooks

Webhook Events

Each fetcher supports subscribing to webhook events. Use client.webhooks.on(eventType, handler) to listen for specific events. Handlers receive an event object containing the original payload and the relevant entity. The SDK automatically fetches the relevant entity data for each event, so you have immediate access to the updated resource without making additional API calls.

Example:

// Using fetcher-specific event handlers:
client.notes.onCreated((event) => {
   console.log('Original payload:', event.payload);
   console.log('New note created:', event.data);
});

// Manually subscribing:
client.webhooks.on('note.created', (event) => {
   console.log('Original payload:', event.payload);
   console.log('New note created:', event.data);
});

Development

1. Clone the repository and install dependencies:

   pnpm install

2. Install the dependencies:

   pnpm install

3. Run the attio-sdk command without building:

   pnpm dev <command> <options>

Contributing

• Open issues or pull requests for bugs and features
• Follow the code style enforced by ESLint

License

MIT