Visible directory

Start here. Returns the team, users, emails, groups, and memberships this key can see.

GET https://ext.trellus.ai/visible

Optionally send a team_id header to select a team you are permitted to read. Match users[].user_id to resource_id in call rows. Memberships connect user_group_id and member_id; member_is_group identifies group members.

The directory includes readable users, a user ID to email mapping, groups and memberships. team appears only when the user can read the whole team. Its absence does not mean authentication failed.

Authentication: send api_key: $TRELLUS_API_KEY. The key inherits the user’s existing permissions. See Authentication.

Request cURLJavaScriptPython

curl https://ext.trellus.ai/visible \
  -H "api_key: $TRELLUS_API_KEY"

const response = await fetch("https://ext.trellus.ai/visible", {
  method: "GET",
  headers: {
    "api_key": process.env.TRELLUS_API_KEY,
  },
});
console.log(await response.text());

import os
import requests

response = requests.get(
    "https://ext.trellus.ai/visible",
    headers={
        "api_key": os.environ["TRELLUS_API_KEY"],
    },
)
print(response.text)

Example response

{
  "team": { "team_id": "...", "team": "..." },
  "users": [{ "user_id": "...", "user_name": "..." }],
  "user_id_to_email": { "...": "rep@example.com" },
  "groups": [],
  "memberships": []
}

Headers

Header	Description
`api_key` Required	`$TRELLUS_API_KEY` The API key belonging to your Trellus user.
`team_id` Optional, string	Selects a team you are permitted to read.

Response

Status	What you receive
200	Readable directory; team is present only with whole-team read access.
Any other status `text/plain`	Read the HTTP status and response text; on 429 honor Retry-After seconds.

More on rows, units and transcripts: Responses and transcripts.

Rate limit

2 requests per 4 seconds per user by default. See Rate limits and exports.

Errors

Error bodies can be plain text. Read the status and the response text.

429 Too Many Requests

Wait the Retry-After number of seconds, then retry with a bounded retry policy. Coordinate workers using the same user key. Default backend limits are per user, not per IP. If only your shared cloud host is blocked despite pacing, give support the UTC time, endpoint and response headers so upstream limits can be investigated.

I need a team-wide read-only key, or my key was exposed

A Trellus API key belongs to a user and inherits their permissions; using it for reporting does not make it a separately restricted credential. Each user can copy their own key in Settings → Integrations → API. Use an appropriately permissioned account for team reporting, verify /visible, and contact support for key replacement if it was exposed.

Every documented case is on Errors and troubleshooting.