API access

Trotto offers an API so you can work with your organization's go links from scripts, integrations, and AI agents. This page covers the three kinds of API key for the links API, plus a separate key used for managing users.

API keys are issued by Trotto — email help@trot.to to request one. Treat any key like a password: it grants access to your organization's data, so keep it secret and let us know if it is ever exposed so we can revoke it.

Kinds of links API key

All keys are sent the same way — in the Authorization header of each request — but they differ in scope and power.

Key	Scope	Permissions
Read-only API key	The whole organization	Read only. Search every listed link in the organization, but cannot create, edit, or delete anything. Rate limited to 50 requests per hour. Built for search — the safe choice for agents and integrations.
Create API key	One user	Search and create links. New links are owned by the key's user. Cannot edit or delete links, and cannot reach anything outside the links API. Rate limited to 50 requests per hour.
Admin API key	An administrator account	Full read and write. Create, edit, and delete links across the organization, read member and usage data, and invite teammates. Not rate limited.

• Choose the read-only API key whenever an integration only needs to look links up — for example, an AI agent that finds the right go link for a teammate. It cannot change anything and can only reach the search endpoint, so it is safe to hand to a third-party tool.
• Choose the create API key for an integration that adds links on one person's behalf — for example, a service that turns tickets into go links. Every link it creates is owned by that user, and it can never edit, delete, or touch account data.
• Choose the admin API key only when you need to manage links across the organization or automate account tasks. It carries an administrator's full permissions, so treat it like an admin login: share it narrowly and store it securely.

Authentication

Send your key in the Authorization header on every request:

Authorization: <YOUR_API_KEY>

A Bearer prefix is also accepted.

Searching for links

Any key can search links.

GET https://trot.to/_/api/links

(Use your own Trotto domain if you have a custom one.)

All query parameters are optional:

Parameter	Description
similar_to	Fuzzy-search shortpaths, best matches first (for example, similar_to=roadmap).
similarity_threshold	A number used with similar_to to drop weak matches. Lower is stricter (for example, 0.5).
destination	Return links whose destination URL is an exact match.
page	Page number, starting at 1. Responses contain at most 20 links per page.

Each link in the response includes both its shortpath and its destination URL, along with the owner, namespace, tags, and visit count.

Example

Search for links related to "roadmap":

curl -H "Authorization: $TROTTO_API_KEY" \
  'https://trot.to/_/api/links?similar_to=roadmap'

Find which shortlinks point at a specific URL:

curl -H "Authorization: $TROTTO_API_KEY" \
  'https://trot.to/_/api/links?destination=https://docs.example.com/roadmap'

Response

A read-only key always returns a paginated object:

{
  "links": [
    {
      "shortpath": "roadmap",
      "destination_url": "https://docs.example.com/roadmap",
      "namespace": "go",
      "owner": "kay@example.com",
      "visits_count": 42,
      "tags": null,
      "id": "123"
    }
  ],
  "page": 1,
  "per_page": 20,
  "total": 187,
  "total_pages": 10
}

To read through all results, request each page in turn until page equals total_pages.

Creating links

A create API key or admin API key can create links:

POST https://trot.to/_/api/links

curl -X POST -H "Authorization: $TROTTO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Origin: <API_ORIGIN_WE_PROVIDE>" \
  -d '{"shortpath": "roadmap", "destination": "https://docs.example.com/roadmap"}' \
  'https://trot.to/_/api/links'

With a create API key the new link is always owned by the key's user; you cannot set a different owner. With an admin API key you may pass an "owner" field to attribute the link to another member of your organization.

The extra header on write requests

Trotto protects its write endpoints against cross-site request forgery (CSRF). A signed-in browser session clears this check automatically, but a request authenticated only by an API key does not — so any write request (create, and, with an admin key, edit or delete) must include one extra header that identifies it as trusted API traffic. We give you the exact header and value when we issue a create or admin key. Use the value exactly as we provide it — it is matched character-for-character and is not a URL, so don't add https:// or a trailing slash. Without the header, the write is rejected with a 400 before the key is even checked. Search requests (GET) never need it.

Editing and deleting links

These operations require the admin API key.

PUT    https://trot.to/_/api/links/<link_id>     # update a link's destination
DELETE https://trot.to/_/api/links/<link_id>     # delete a link

A create API key cannot edit or delete anything (it will receive a 403). Because the admin key acts with an administrator's permissions, it can also manage links across the organization, read member and usage data, and invite users — the same actions an administrator can take in the dashboard.

Limits and permissions

• The read-only API key and create API key are each rate limited to 50 requests per hour and confined to the links API — they cannot reach user, stats, or account data. The read-only key rejects every write; the create key allows only creation (no edit or delete). similar_to search terms are limited to 256 characters.
• The admin API key has full read-write access and is not rate limited. Guard it accordingly.

If a request is rejected, the response status tells you why: 400 for a write missing the required header above; 401 for a missing, invalid, or revoked key; 403 for an action a key is not permitted to take; 429 when a key's hourly rate limit is exceeded.

Managing users with the API

Managing links is separate from managing users. Trotto offers a distinct organization-wide API key for user management — provisioning and deprovisioning members, and syncing them from your identity provider (SCIM). This is a different key from the links keys above, and is not interchangeable with them.

If you want to automate user management or connect Trotto to your identity provider, email help@trot.to and we'll set up the appropriate key.