Attrove Entities API
The Entities API from Attrove — 3 operation(s) for entities.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/attrove-com:attrove-com-entities-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Attrove Entities API
description: Attrove public API, partner, and A2A endpoints
version: v1
servers:
- url: http://0.0.0.0:3000
tags:
- name: Entities
paths:
/v1/users/{user_id}/entities:
get:
summary: List contacts
tags:
- Entities
description: 'Returns contacts (people and bots) that the authenticated user has communicated with.
**Use cases**:
- Discover entity IDs for filtering messages by sender via `GET /v1/users/:user_id/messages?entity_id=ent_xxx`
- Build a contact picker UI
- Show sender details in inbox views
**Filtering**:
- `search`: Case-insensitive substring match on contact name, or exact match on an external ID (email address, Slack user ID)
- `entity_type`: Filter by type (e.g., "person", "bot")
- `is_bot`: Filter by bot status (true/false)
**Pagination (cursor-only)**:
- `limit`: Maximum number of contacts per page (default: 50, max: 100)
- `cursor`: Opaque token from `pagination.next_cursor` of a prior response. Pass it back unchanged to fetch the next page. Omit on the first page.
The response `pagination` object contains `limit`, `has_more`, and (when `has_more=true`) `next_cursor`. There is no `offset` and no `total_count` — partners walk pages forward via cursor and use `has_more` to detect the last page.
**Examples**:
```
# List all contacts
GET /v1/users/:user_id/entities
# Search by name or email
GET /v1/users/:user_id/entities?search=john
# Only non-bot contacts
GET /v1/users/:user_id/entities?is_bot=false
# Filter by type
GET /v1/users/:user_id/entities?entity_type=person
```'
parameters:
- schema:
type: string
minLength: 1
in: query
name: search
required: false
description: Search by name (substring, case-insensitive) or external ID (exact match)
- schema:
type: string
in: query
name: entity_type
required: false
description: Filter by entity type (e.g., "person", "bot")
- schema:
type: string
enum:
- 'true'
- 'false'
in: query
name: is_bot
required: false
description: Filter by bot status
- schema:
type: string
pattern: ^[0-9]+$
in: query
name: limit
required: false
description: Number of items to return (1-100, default 50)
- schema:
type: string
in: query
name: cursor
required: false
description: Opaque pagination cursor returned as `pagination.next_cursor` from a prior response. Pass it back unchanged to fetch the next page. Cursors are sort-key bound — a cursor from one endpoint cannot be reused on another.
- schema:
type: string
format: uuid
in: path
name: user_id
required: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
success:
type: boolean
enum:
- true
data:
type: array
items:
type: object
additionalProperties: false
properties:
id:
type: string
pattern: ^ent_[A-Za-z0-9:]+$
name:
type: string
entity_type:
type: string
external_ids:
type: array
items:
type: string
is_bot:
type: boolean
avatar_uri:
anyOf:
- type: string
- type: 'null'
required:
- id
- name
- entity_type
- external_ids
- is_bot
- avatar_uri
pagination:
type: object
oneOf:
- type: object
additionalProperties: false
properties:
limit:
type: number
has_more:
type: boolean
enum:
- true
next_cursor:
type: string
required:
- limit
- has_more
- next_cursor
- type: object
additionalProperties: false
properties:
limit:
type: number
has_more:
type: boolean
enum:
- false
required:
- limit
- has_more
required:
- success
- data
- pagination
'400':
description: Default Response
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
success:
type: boolean
enum:
- false
error:
type: object
additionalProperties: false
properties:
code:
type: string
description: Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)
message:
type: string
description: Human-readable error message
details:
description: Optional additional error context
required:
- code
- message
required:
- success
- error
'403':
description: Default Response
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
success:
type: boolean
enum:
- false
error:
type: object
additionalProperties: false
properties:
code:
type: string
description: Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)
message:
type: string
description: Human-readable error message
details:
description: Optional additional error context
required:
- code
- message
required:
- success
- error
'500':
description: Default Response
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
success:
type: boolean
enum:
- false
error:
type: object
additionalProperties: false
properties:
code:
type: string
description: Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)
message:
type: string
description: Human-readable error message
details:
description: Optional additional error context
required:
- code
- message
required:
- success
- error
operationId: getV1UsersByUserIdEntities
x-operation-id-source: derived
/v1/users/{user_id}/entities/relationships:
get:
summary: List entity relationships
tags:
- Entities
description: Returns pairs of entities that co-occur on messages, meetings, or calendar events, with interaction count and recency.
parameters:
- schema:
type: string
in: query
name: limit
required: false
description: Max results (default 200, max 500)
- schema:
type: string
in: query
name: min_interactions
required: false
description: Minimum co-occurrence count (default 1)
- schema:
type: string
enum:
- 'true'
- 'false'
in: query
name: include_bots
required: false
description: Include bot entities (default false)
- schema:
type: string
format: uuid
in: path
name: user_id
required: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
success:
type: boolean
enum:
- true
data:
type: array
items:
type: object
properties:
entity_a:
type: object
additionalProperties: false
properties:
id:
type: string
pattern: ^ent_[A-Za-z0-9:]+$
name:
type: string
entity_type:
type: string
external_ids:
type: array
items:
type: string
is_bot:
type: boolean
avatar_uri:
anyOf:
- type: string
- type: 'null'
required:
- id
- name
- entity_type
- external_ids
- is_bot
- avatar_uri
entity_b:
type: object
additionalProperties: false
properties:
id:
type: string
pattern: ^ent_[A-Za-z0-9:]+$
name:
type: string
entity_type:
type: string
external_ids:
type: array
items:
type: string
is_bot:
type: boolean
avatar_uri:
anyOf:
- type: string
- type: 'null'
required:
- id
- name
- entity_type
- external_ids
- is_bot
- avatar_uri
co_occurrence_count:
type: integer
minimum: 1
last_interaction_at:
anyOf:
- type: string
- type: 'null'
required:
- entity_a
- entity_b
- co_occurrence_count
- last_interaction_at
pagination:
type: object
properties:
limit:
type: number
offset:
type: number
has_more:
type: boolean
total_count:
type: number
required:
- limit
- offset
- has_more
required:
- success
- data
- pagination
'400':
description: Default Response
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
success:
type: boolean
enum:
- false
error:
type: object
additionalProperties: false
properties:
code:
type: string
description: Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)
message:
type: string
description: Human-readable error message
details:
description: Optional additional error context
required:
- code
- message
required:
- success
- error
'403':
description: Default Response
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
success:
type: boolean
enum:
- false
error:
type: object
additionalProperties: false
properties:
code:
type: string
description: Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)
message:
type: string
description: Human-readable error message
details:
description: Optional additional error context
required:
- code
- message
required:
- success
- error
'500':
description: Default Response
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
success:
type: boolean
enum:
- false
error:
type: object
additionalProperties: false
properties:
code:
type: string
description: Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)
message:
type: string
description: Human-readable error message
details:
description: Optional additional error context
required:
- code
- message
required:
- success
- error
operationId: getV1UsersByUserIdEntitiesRelationships
x-operation-id-source: derived
/v1/users/{user_id}/entities/{id}:
get:
summary: Retrieve a contact
tags:
- Entities
description: 'Retrieves a specific contact by its ID (ent_xxx format or raw UUID). The contact must belong to the authenticated user.
**Response fields**:
- `id`: Entity ID (ent_xxx opaque format)
- `name`: Human-readable name
- `entity_type`: Type of entity ("person", "bot", etc.)
- `external_ids`: Platform-specific identifiers (email addresses, Slack user IDs, etc.)
- `is_bot`: Whether this contact is a bot/automated sender
- `avatar_uri`: URI to the contact''s avatar image (null if unavailable)'
parameters:
- schema:
type: string
format: uuid
in: path
name: user_id
required: true
- schema:
type: string
in: path
name: id
required: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
success:
type: boolean
enum:
- true
data:
type: object
additionalProperties: false
properties:
id:
type: string
pattern: ^ent_[A-Za-z0-9:]+$
name:
type: string
entity_type:
type: string
external_ids:
type: array
items:
type: string
is_bot:
type: boolean
avatar_uri:
anyOf:
- type: string
- type: 'null'
required:
- id
- name
- entity_type
- external_ids
- is_bot
- avatar_uri
required:
- success
- data
'400':
description: Default Response
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
success:
type: boolean
enum:
- false
error:
type: object
additionalProperties: false
properties:
code:
type: string
description: Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)
message:
type: string
description: Human-readable error message
details:
description: Optional additional error context
required:
- code
- message
required:
- success
- error
'403':
description: Default Response
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
success:
type: boolean
enum:
- false
error:
type: object
additionalProperties: false
properties:
code:
type: string
description: Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)
message:
type: string
description: Human-readable error message
details:
description: Optional additional error context
required:
- code
- message
required:
- success
- error
'404':
description: Default Response
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
success:
type: boolean
enum:
- false
error:
type: object
additionalProperties: false
properties:
code:
type: string
description: Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)
message:
type: string
description: Human-readable error message
details:
description: Optional additional error context
required:
- code
- message
required:
- success
- error
'500':
description: Default Response
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
success:
type: boolean
enum:
- false
error:
type: object
additionalProperties: false
properties:
code:
type: string
description: Machine-readable error code (e.g., AUTH_INVALID_TOKEN, RESOURCE_NOT_FOUND)
message:
type: string
description: Human-readable error message
details:
description: Optional additional error context
required:
- code
- message
required:
- success
- error
operationId: getV1UsersByUserIdEntitiesById
x-operation-id-source: derived