1eye Docs – Buyer Signals API, Webhooks, MCP & Integrations

Manage active and pending users in the workspace associated with your API key. Invite teammates, update names and roles, and remove workspace memberships.

Base URL

https://api.1eye.ai/v1/users

Authentication

All requests require a workspace API key:

Authorization: Bearer 1eye_live_xxxxxxxxx

The examples use $API_KEY for your API key. The key determines the workspace; you do not supply a workspace ID. See Authentication.

Endpoints

Method	Endpoint	Description
`GET`	`/v1/users`	List active and pending users.
`GET`	`/v1/users/{user_id}`	Retrieve a user.
`POST`	`/v1/users`	Invite a user by email and role.
`PATCH`	`/v1/users/{user_id}`	Update a name or role.
`DELETE`	`/v1/users/{user_id}`	Remove a workspace membership.

User object

{
  "id": "usr_123456789012345678",
  "name": "Jane Doe",
  "email": "jane@snowbricks.example",
  "role": "admin",
  "status": "active",
  "last_login_at": "2026-10-20T17:30:00Z",
  "created_at": "2026-10-18T18:00:00Z",
  "updated_at": "2026-10-20T18:00:00Z"
}

All names, domains, identifiers, amounts, URLs, and timestamps in these examples are illustrative.

Field	Type	Description
`id`	string	Workspace User ID (`usr_`).
`name`	string or null	Display name; may be unavailable for a pending invitation.
`email`	string	Membership email. Read-only after invitation.
`role`	string	`admin`, `marketer`, or `viewer`.
`status`	string	`active` or `pending` in public responses.
`last_login_at`	datetime or null	Last login timestamp in UTC, if available.
`created_at`	datetime	Creation timestamp in UTC.
`updated_at`	datetime	Last modification timestamp in UTC.

Roles

Role	Purpose
`admin`	Workspace administration, subject to the operation’s authorization rules.
`marketer`	Marketing and GTM work within the assigned permissions.
`viewer`	Read access within the assigned permissions.

Deleted memberships are inaccessible through all Users GET endpoints. User objects do not expose credentials or invitation tokens.

1. List users

GET /v1/users

curl "https://api.1eye.ai/v1/users?limit=100" \
  -H "Authorization: Bearer $API_KEY"

Query parameters

Parameter	Type	Description
`status`	string	`active` or `pending`. Omit to return both.
`role`	string	`admin`, `marketer`, or `viewer`. Omit for all roles.
`limit`	integer	Results per page. Default: `100`. Range: `1–1000`.
`cursor`	string	Opaque cursor returned by the previous page.

Combine filters to retrieve, for example, pending viewers:

curl "https://api.1eye.ai/v1/users?status=pending&role=viewer&limit=100" \
  -H "Authorization: Bearer $API_KEY"

Example response

200 OK

{
  "total": 2,
  "data": [
    {
      "id": "usr_987654321098765432",
      "name": null,
      "email": "alex@snowbricks.example",
      "role": "viewer",
      "status": "pending",
      "last_login_at": null,
      "created_at": "2026-10-20T18:00:00Z",
      "updated_at": "2026-10-20T18:00:00Z"
    },
    {
      "id": "usr_123456789012345678",
      "name": "Jane Doe",
      "email": "jane@snowbricks.example",
      "role": "admin",
      "status": "active",
      "last_login_at": "2026-10-20T17:30:00Z",
      "created_at": "2026-10-18T18:00:00Z",
      "updated_at": "2026-10-20T18:00:00Z"
    }
  ],
  "pagination": {
    "next_cursor": null
  }
}

The unfiltered collection includes active and pending users only. status=deleted and status=all are invalid.

Pagination and ordering

Users are ordered by created_at DESC, then id DESC. Pass pagination.next_cursor unchanged with the same filters for the next page. Stop when it is null. No configurable sort parameters or offset pagination are supported. An empty result returns total: 0, data: [], and pagination.next_cursor: null.

2. Retrieve a user

GET /v1/users/{user_id}

curl "https://api.1eye.ai/v1/users/usr_123456789012345678" \
  -H "Authorization: Bearer $API_KEY"

200 OK — returns one User object directly, as shown above. Active and pending memberships are accessible. Missing, deleted, or inaccessible IDs all return 404 not_found.

3. Invite a user

POST /v1/users POST accepts exactly email and role; both are required. It creates a pending membership and sends the existing invitation workflow.

curl -X POST "https://api.1eye.ai/v1/users" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "alex@snowbricks.example",
  "role": "viewer"
}'

Example response

201 Created

{
  "id": "usr_987654321098765432",
  "name": null,
  "email": "alex@snowbricks.example",
  "role": "viewer",
  "status": "pending",
  "last_login_at": null,
  "created_at": "2026-10-20T18:00:00Z",
  "updated_at": "2026-10-20T18:00:00Z"
}

The invited user remains pending until they complete onboarding. The API cannot activate a user by setting status. Email must be valid and at most 254 characters. An active or pending membership with the same normalized email in this workspace causes a 400 validation error. The same email can independently belong to other workspaces. POST does not accept name, status, IDs, timestamps, or workspace selectors. A previously deleted email may be invited again as a new pending membership with a new User ID.

4. Update a user

PATCH /v1/users/{user_id} PATCH accepts name, role, or both. At least one must be supplied.

curl -X PATCH "https://api.1eye.ai/v1/users/usr_987654321098765432" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Alex Doe",
  "role": "marketer"
}'

Example response

200 OK — returns the complete updated User object.

{
  "id": "usr_987654321098765432",
  "name": "Alex Doe",
  "email": "alex@snowbricks.example",
  "role": "marketer",
  "status": "pending",
  "last_login_at": null,
  "created_at": "2026-10-20T18:00:00Z",
  "updated_at": "2026-10-21T18:00:00Z"
}

Omitted fields are preserved. Name must be a nonempty string after trimming, no more than 160 characters, without control characters. null is invalid for name. Role must be admin, marketer, or viewer. Email, status, login timestamps, and system fields are read-only. PATCH does not resend an invitation or activate a pending user. Validation is atomic.

5. Delete a user

DELETE /v1/users/{user_id}

curl -X DELETE "https://api.1eye.ai/v1/users/usr_987654321098765432" \
  -H "Authorization: Bearer $API_KEY"

204 No Content — the response body is empty. Deletion removes this workspace membership through soft deletion. The membership immediately disappears from list results and cannot be retrieved, updated, or deleted again through its old ID. Historical attribution remains retained internally. Memberships in other workspaces are unaffected. No restore endpoint is available.

Administrator protection

Every established workspace must retain at least one active administrator. The last active admin cannot be deleted or demoted. A pending admin does not satisfy this requirement, and admins in another workspace do not count. All management operations require the appropriate permissions. An API key cannot grant itself permissions it does not possess.

Errors

Status	Error code	Description
400	`invalid_parameter`	A request field or query parameter is invalid.
400	`invalid_request`	An operation would remove or demote the last active administrator.
400	`invalid_cursor`	The cursor is malformed or does not match the filters.
404	`not_found`	The user is missing, deleted, or inaccessible.
401	`authentication_error`	The API key is missing, invalid, or revoked.
403	`permission_denied`	The key does not have permission for this operation.
429	`rate_limit_exceeded`	The workspace API rate limit was exceeded.
500	`internal_error`	An unexpected server error occurred.
503	`service_unavailable`	The service is temporarily unavailable.

Errors use the standard error envelope. Use request_id when contacting support.

Duplicate email error

{
  "error": {
    "code": "invalid_parameter",
    "message": "A user with this email already exists in the Workspace.",
    "param": "email",
    "request_id": "req_123456789012345678"
  }
}

Get Started

Buyers

Signals

Target Lists

Destinations

Knowledge Base

Workspace

Users

Base URL

Authentication

Endpoints

User object

Roles

1. List users

Query parameters

Example response

2. Retrieve a user

3. Invite a user

Example response

4. Update a user

Example response

5. Delete a user

Administrator protection

Errors

Duplicate email error

​Base URL

​Authentication

​Endpoints

​User object

​Roles

​1. List users

​Query parameters

​Example response

​Pagination and ordering

​2. Retrieve a user

​3. Invite a user

​Example response

​4. Update a user

​Example response

​5. Delete a user

​Administrator protection

​Errors

​Duplicate email error

Base URL

Authentication

Endpoints

User object

Roles

1. List users

Query parameters

Example response

Pagination and ordering

2. Retrieve a user

3. Invite a user

Example response

4. Update a user

Example response

5. Delete a user

Administrator protection

Errors

Duplicate email error