Attio Hello World Skill

Attio Hello World

Overview

Five progressively deeper API calls that exercise the Attio object/record model. Every call targets https://api.attio.com/v2 and returns JSON.

Prerequisites

Completed attio-install-auth (valid ATTIO_API_KEY in env)
Scopes: object_configuration:read, record_permission:read, record_permission:read-write

Instructions

Step 1: List Workspace Objects

Every Attio workspace has system objects (people, companies) and optional objects (deals, users, workspaces). Custom objects can be created.

curl -s https://api.attio.com/v2/objects \
  -H "Authorization: Bearer ${ATTIO_API_KEY}" | jq '.data[] | {slug: .api_slug, singular: .singular_noun}'

{"slug": "people", "singular": "Person"}
{"slug": "companies", "singular": "Company"}
{"slug": "deals", "singular": "Deal"}

Step 2: List Attributes on an Object

Objects have attributes (fields). Use the slug from Step 1.

curl -s "https://api.attio.com/v2/objects/people/attributes" \
  -H "Authorization: Bearer ${ATTIO_API_KEY}" | jq '.data[] | {slug: .api_slug, type: .type}'

Common people attributes: name (personal-name), email_addresses (email-address), phone_numbers (phone-number), description (text), primary_location (location), company (record-reference).

Step 3: Create a Person Record

const person = await attioFetch<{ data: { id: { record_id: string } } }>({
  method: "POST",
  path: "/objects/people/records",
  body: {
    data: {
      values: {
        email_addresses: ["ada@example.com"],
        name: [
          {
            first_name: "Ada",
            last_name: "Lovelace",
            full_name: "Ada Lovelace",
          },
        ],
        description: ["First computer programmer"],
      },
    },
  },
});

console.log("Created person:", person.data.id.record_id);

Key detail: Values are keyed by attribute slug. Most attributes accept an array (Attio supports multiselect by default). String shortcuts work for emails and domains.

Step 4: Query Records with Filters

// List people whose email contains "example.com"
const results = await attioFetch<{
  data: Array<{ id: { record_id: string }; values: Record<string, any> }>;
}>({
  method: "POST",
  path: "/objects/people/records/query",
  body: {
    filter: {
      email_addresses: {
        email_address: { $contains: "example.com" },
      },
    },
    sorts: [
      {
        attribute: "created_at",
        field: "created_at",
        direction: "desc",
      },
    ],
    limit: 10,
  },
});

console.log(`Found ${results.data.length} people`);

Step 5: Create a Company and Link It

// Create company
const company = await attioFetch<{ data: { id: { record_id: string } } }>({
  method: "POST",
  path: "/objects/companies/records",
  body: {
    data: {
      values: {
        name: ["Acme Corp"],
        domains: ["acme.com"],
        description: ["Enterprise widget manufacturer"],
      },
    },
  },
});

// Update person to link to company via record-reference
await attioFetch({
  method: "PATCH",
  path: `/objects/people/records/${person.data.id.record_id}`,
  body: {
    data: {
      values: {
        company: [
          {
            target_object: "companies",
            target_record_id: company.data.id.record_id,
          },
        ],
      },
    },
  },
});

Attio Data Model Quick Reference

Workspace
 └── Objects (people, companies, deals, custom)
      ├── Attributes (name, email, phone, custom)
      └── Records (individual people, companies)
           └── Values (attribute data on each record)

 └── Lists (pipelines, boards, custom groupings)
      └── Entries (records added to a list with list-specific attributes)

Error Handling

| Error | Status | Cause | Solution | |-------|--------|-------|----------| | not_found | 404 | Wrong object slug or record ID | Verify slug with GET /v2/objects | | validation_error | 422 | Invalid attribute value format | Check attribute type in docs | | insufficient_scopes | 403 | Token missing write scope | Add record_permission:read-write | | duplicate_record | 409 | Record with same unique field exists | Use PUT (assert) instead |

Resources

Next Steps

Proceed to attio-local-dev-loop for development workflow, or attio-core-workflow-a for record CRUD patterns.

Agent Skills: Attio Hello World

Install this agent skill to your local

Skill Files