openapi: 3.0.3
info:
  title: Attio REST API
  description: >-
    The Attio REST API exposes the Attio CRM's object/attribute/record data model
    over HTTPS. Attio is an AI-native CRM built on flexible objects (people,
    companies, deals, users, workspaces, and custom objects), typed attributes,
    records, and lists. This specification covers the core data-model, activity,
    collaboration, and platform endpoints: objects, records, attributes, lists,
    list entries, notes, tasks, comments, threads, webhooks, workspace members,
    and token identification. All requests are authenticated with a Bearer access
    token (API key or OAuth) and scoped by granular permissions. Endpoints marked
    modeled in the repository review were derived from Attio's published endpoint
    reference and follow Attio's documented /v2 path conventions.
  version: '2.0'
  contact:
    name: Attio
    url: https://attio.com
  license:
    name: Proprietary
    url: https://attio.com/legal
servers:
  - url: https://api.attio.com/v2
    description: Attio REST API v2
security:
  - bearerAuth: []
tags:
  - name: Objects
    description: Top-level data model - people, companies, deals, and custom objects.
  - name: Records
    description: Individual records within an object, with CRUD, query, and upsert.
  - name: Attributes
    description: Typed fields defined on objects and lists, plus select options and statuses.
  - name: Lists
    description: Collections that model a process by referencing records.
  - name: List Entries
    description: Entries within a list, referencing a parent record.
  - name: Notes
    description: Free-form notes attached to records.
  - name: Tasks
    description: Actionable to-dos with deadlines and assignees.
  - name: Comments
    description: Comments within threads on records and list entries.
  - name: Threads
    description: Threads of comments on records and list entries.
  - name: Webhooks
    description: Webhook subscriptions delivering signed HTTP callbacks on changes.
  - name: Workspace Members
    description: Human users belonging to the workspace.
  - name: Meta
    description: Access token identification and introspection.
paths:
  /objects:
    get:
      operationId: listObjects
      tags: [Objects]
      summary: List objects
      description: Lists all system-defined and user-defined objects in your workspace.
      responses:
        '200':
          description: A list of objects.
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createObject
      tags: [Objects]
      summary: Create an object
      description: Creates a new custom object in your workspace.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The created object.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /objects/{object}:
    parameters:
      - $ref: '#/components/parameters/Object'
    get:
      operationId: getObject
      tags: [Objects]
      summary: Get an object
      description: Gets a single object by its ID or slug.
      responses:
        '200':
          description: The requested object.
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateObject
      tags: [Objects]
      summary: Update an object
      description: Updates a single object.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The updated object.
  /objects/{object}/records/query:
    parameters:
      - $ref: '#/components/parameters/Object'
    post:
      operationId: listRecords
      tags: [Records]
      summary: List records
      description: >-
        Lists people, company, or other records, with the option to filter and
        sort results. Confirmed endpoint - POST /v2/objects/{object}/records/query.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                filter:
                  type: object
                sorts:
                  type: array
                  items:
                    type: object
                limit:
                  type: integer
                offset:
                  type: integer
      responses:
        '200':
          description: A page of matching records.
  /objects/{object}/records:
    parameters:
      - $ref: '#/components/parameters/Object'
    post:
      operationId: createRecord
      tags: [Records]
      summary: Create a record
      description: Creates a new person, company, or other record.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The created record.
    put:
      operationId: assertRecord
      tags: [Records]
      summary: Assert a record
      description: >-
        Creates or updates (upserts) a record using a matching attribute to
        determine whether a record already exists.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The asserted (created or updated) record.
  /objects/{object}/records/{record_id}:
    parameters:
      - $ref: '#/components/parameters/Object'
      - $ref: '#/components/parameters/RecordId'
    get:
      operationId: getRecord
      tags: [Records]
      summary: Get a record
      description: Gets a single record by its record_id.
      responses:
        '200':
          description: The requested record.
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateRecordAppend
      tags: [Records]
      summary: Update a record (append multiselect values)
      description: Updates a record, appending values to multiselect attributes.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The updated record.
    put:
      operationId: updateRecordOverwrite
      tags: [Records]
      summary: Update a record (overwrite multiselect values)
      description: Updates a record, overwriting values on multiselect attributes.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The updated record.
    delete:
      operationId: deleteRecord
      tags: [Records]
      summary: Delete a record
      description: Deletes a record by its record_id.
      responses:
        '200':
          description: The record was deleted.
  /objects/{object}/records/{record_id}/attributes/{attribute}/values:
    parameters:
      - $ref: '#/components/parameters/Object'
      - $ref: '#/components/parameters/RecordId'
      - $ref: '#/components/parameters/Attribute'
    get:
      operationId: listRecordAttributeValues
      tags: [Records]
      summary: List record attribute values
      description: Lists all values, including historic values, for a given attribute on a record.
      responses:
        '200':
          description: A list of attribute values.
  /objects/{object}/records/{record_id}/entries:
    parameters:
      - $ref: '#/components/parameters/Object'
      - $ref: '#/components/parameters/RecordId'
    get:
      operationId: listRecordEntries
      tags: [Records]
      summary: List record entries
      description: Lists all entries, across all lists, for which this record is the parent.
      responses:
        '200':
          description: A list of list entries.
  /{target}/{identifier}/attributes:
    parameters:
      - $ref: '#/components/parameters/Target'
      - $ref: '#/components/parameters/Identifier'
    get:
      operationId: listAttributes
      tags: [Attributes]
      summary: List attributes
      description: Lists all attributes defined on a specific object or list.
      responses:
        '200':
          description: A list of attributes.
    post:
      operationId: createAttribute
      tags: [Attributes]
      summary: Create an attribute
      description: Creates a new attribute on either an object or a list.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The created attribute.
  /{target}/{identifier}/attributes/{attribute}:
    parameters:
      - $ref: '#/components/parameters/Target'
      - $ref: '#/components/parameters/Identifier'
      - $ref: '#/components/parameters/Attribute'
    get:
      operationId: getAttribute
      tags: [Attributes]
      summary: Get an attribute
      description: Gets information about a single attribute on either an object or a list.
      responses:
        '200':
          description: The requested attribute.
    patch:
      operationId: updateAttribute
      tags: [Attributes]
      summary: Update an attribute
      description: Updates a single attribute on a given object or list.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The updated attribute.
  /{target}/{identifier}/attributes/{attribute}/options:
    parameters:
      - $ref: '#/components/parameters/Target'
      - $ref: '#/components/parameters/Identifier'
      - $ref: '#/components/parameters/Attribute'
    get:
      operationId: listSelectOptions
      tags: [Attributes]
      summary: List select options
      description: Lists all select options for a particular select-type attribute.
      responses:
        '200':
          description: A list of select options.
    post:
      operationId: createSelectOption
      tags: [Attributes]
      summary: Create a select option
      description: Adds a new option to a select-type attribute.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The created select option.
  /{target}/{identifier}/attributes/{attribute}/statuses:
    parameters:
      - $ref: '#/components/parameters/Target'
      - $ref: '#/components/parameters/Identifier'
      - $ref: '#/components/parameters/Attribute'
    get:
      operationId: listStatuses
      tags: [Attributes]
      summary: List statuses
      description: Lists all statuses for a particular status-type attribute.
      responses:
        '200':
          description: A list of statuses.
    post:
      operationId: createStatus
      tags: [Attributes]
      summary: Create a status
      description: Adds a new status to a status-type attribute.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The created status.
  /lists:
    get:
      operationId: listLists
      tags: [Lists]
      summary: List all lists
      description: Lists all lists that your access token has access to.
      responses:
        '200':
          description: A list of lists.
    post:
      operationId: createList
      tags: [Lists]
      summary: Create a list
      description: Creates a new list.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The created list.
  /lists/{list}:
    parameters:
      - $ref: '#/components/parameters/List'
    get:
      operationId: getList
      tags: [Lists]
      summary: Get a list
      description: Gets a single list by its ID or slug.
      responses:
        '200':
          description: The requested list.
    patch:
      operationId: updateList
      tags: [Lists]
      summary: Update a list
      description: Updates an existing list.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The updated list.
  /lists/{list}/entries/query:
    parameters:
      - $ref: '#/components/parameters/List'
    post:
      operationId: listEntries
      tags: [List Entries]
      summary: List entries
      description: Lists entries in a given list, with the option to filter and sort results.
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: A page of list entries.
  /lists/{list}/entries:
    parameters:
      - $ref: '#/components/parameters/List'
    post:
      operationId: createEntry
      tags: [List Entries]
      summary: Create an entry
      description: Adds a record to a list as a new list entry.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The created list entry.
    put:
      operationId: assertEntry
      tags: [List Entries]
      summary: Assert a list entry by parent
      description: Creates or updates a list entry, keyed by its parent record.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The asserted list entry.
  /lists/{list}/entries/{entry_id}:
    parameters:
      - $ref: '#/components/parameters/List'
      - $ref: '#/components/parameters/EntryId'
    get:
      operationId: getEntry
      tags: [List Entries]
      summary: Get a list entry
      description: Gets a single list entry by its entry_id.
      responses:
        '200':
          description: The requested list entry.
    patch:
      operationId: updateEntryAppend
      tags: [List Entries]
      summary: Update a list entry (append multiselect values)
      description: Updates a list entry, appending values to multiselect attributes.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The updated list entry.
    put:
      operationId: updateEntryOverwrite
      tags: [List Entries]
      summary: Update a list entry (overwrite multiselect values)
      description: Updates a list entry, overwriting values on multiselect attributes.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The updated list entry.
    delete:
      operationId: deleteEntry
      tags: [List Entries]
      summary: Delete a list entry
      description: Deletes a list entry by its entry_id.
      responses:
        '200':
          description: The list entry was deleted.
  /notes:
    get:
      operationId: listNotes
      tags: [Notes]
      summary: List notes
      description: Lists notes for all records or for a specific record.
      parameters:
        - name: parent_object
          in: query
          schema:
            type: string
        - name: parent_record_id
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
        - name: offset
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: A list of notes.
    post:
      operationId: createNote
      tags: [Notes]
      summary: Create a note
      description: Creates a new note for a given record.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The created note.
  /notes/{note_id}:
    parameters:
      - name: note_id
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: getNote
      tags: [Notes]
      summary: Get a note
      description: Gets a single note by its note_id.
      responses:
        '200':
          description: The requested note.
    delete:
      operationId: deleteNote
      tags: [Notes]
      summary: Delete a note
      description: Deletes a note by its note_id.
      responses:
        '200':
          description: The note was deleted.
  /tasks:
    get:
      operationId: listTasks
      tags: [Tasks]
      summary: List tasks
      description: Lists all tasks.
      responses:
        '200':
          description: A list of tasks.
    post:
      operationId: createTask
      tags: [Tasks]
      summary: Create a task
      description: Creates a new task.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The created task.
  /tasks/{task_id}:
    parameters:
      - name: task_id
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: getTask
      tags: [Tasks]
      summary: Get a task
      description: Gets a single task by its task_id.
      responses:
        '200':
          description: The requested task.
    patch:
      operationId: updateTask
      tags: [Tasks]
      summary: Update a task
      description: Updates a task's deadline, completion status, or assignees.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The updated task.
    delete:
      operationId: deleteTask
      tags: [Tasks]
      summary: Delete a task
      description: Deletes a task by its task_id.
      responses:
        '200':
          description: The task was deleted.
  /comments:
    post:
      operationId: createComment
      tags: [Comments]
      summary: Create a comment
      description: Creates a new comment related to an existing thread, record, or entry.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The created comment.
  /comments/{comment_id}:
    parameters:
      - name: comment_id
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: getComment
      tags: [Comments]
      summary: Get a comment
      description: Gets a single comment by its comment_id.
      responses:
        '200':
          description: The requested comment.
    delete:
      operationId: deleteComment
      tags: [Comments]
      summary: Delete a comment
      description: Deletes a comment by its comment_id.
      responses:
        '200':
          description: The comment was deleted.
  /threads:
    get:
      operationId: listThreads
      tags: [Threads]
      summary: List threads
      description: Lists threads of comments on a record or list entry.
      parameters:
        - name: record_id
          in: query
          schema:
            type: string
        - name: entry_id
          in: query
          schema:
            type: string
      responses:
        '200':
          description: A list of threads.
  /threads/{thread_id}:
    parameters:
      - name: thread_id
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: getThread
      tags: [Threads]
      summary: Get a thread
      description: Gets all comments in a thread.
      responses:
        '200':
          description: The requested thread with its comments.
  /webhooks:
    get:
      operationId: listWebhooks
      tags: [Webhooks]
      summary: List webhooks
      description: Gets all of the webhooks in your workspace.
      responses:
        '200':
          description: A list of webhooks.
    post:
      operationId: createWebhook
      tags: [Webhooks]
      summary: Create a webhook
      description: Creates a webhook and its associated event subscriptions.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The created webhook.
  /webhooks/{webhook_id}:
    parameters:
      - name: webhook_id
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: getWebhook
      tags: [Webhooks]
      summary: Get a webhook
      description: Gets a single webhook by its webhook_id.
      responses:
        '200':
          description: The requested webhook.
    patch:
      operationId: updateWebhook
      tags: [Webhooks]
      summary: Update a webhook
      description: Updates a webhook and its associated subscriptions.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The updated webhook.
    delete:
      operationId: deleteWebhook
      tags: [Webhooks]
      summary: Delete a webhook
      description: Deletes a webhook by its webhook_id.
      responses:
        '200':
          description: The webhook was deleted.
  /workspace_members:
    get:
      operationId: listWorkspaceMembers
      tags: [Workspace Members]
      summary: List workspace members
      description: Lists all workspace members in the workspace.
      responses:
        '200':
          description: A list of workspace members.
  /workspace_members/{workspace_member_id}:
    parameters:
      - name: workspace_member_id
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: getWorkspaceMember
      tags: [Workspace Members]
      summary: Get a workspace member
      description: Gets a single workspace member by its ID.
      responses:
        '200':
          description: The requested workspace member.
  /self:
    get:
      operationId: identifySelf
      tags: [Meta]
      summary: Identify
      description: >-
        Identifies the current access token, the workspace it is linked to, the
        authorizing member, and any permissions/scopes it holds.
      responses:
        '200':
          description: The access token identity and permissions.
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Attio access token (API key or OAuth 2.0 bearer token) with the required scopes.
  parameters:
    Object:
      name: object
      in: path
      required: true
      description: The object ID or slug (for example people, companies, deals, or a custom object).
      schema:
        type: string
    RecordId:
      name: record_id
      in: path
      required: true
      schema:
        type: string
    Attribute:
      name: attribute
      in: path
      required: true
      description: The attribute ID or slug.
      schema:
        type: string
    Target:
      name: target
      in: path
      required: true
      description: Whether the attribute belongs to an object or a list.
      schema:
        type: string
        enum: [objects, lists]
    Identifier:
      name: identifier
      in: path
      required: true
      description: The ID or slug of the object or list the attribute belongs to.
      schema:
        type: string
    List:
      name: list
      in: path
      required: true
      description: The list ID or slug.
      schema:
        type: string
    EntryId:
      name: entry_id
      in: path
      required: true
      schema:
        type: string
  responses:
    Unauthorized:
      description: The access token is missing, invalid, or lacks the required scope.
    NotFound:
      description: The requested resource was not found.