canonical: https://jentic.com/apis/gettruss.io/gettruss

# Gettruss Truss API

The Truss API provides programmatic access to the Truss file collection and project management platform. Across 43 endpoints it covers contacts, projects, tasks, users, entities, and drive folders, letting external tools sync project data, automate task creation, and search contacts. Authentication is bearer-token based, and most resources expose list, retrieve, and update operations alongside helpers like idempotency-key lookup and status transitions on projects.

## For AI agents

Manage projects, tasks, contacts, and drive folders in the Truss platform via 43 endpoints with bearer-token authentication.

## Scope

Does not handle invoicing, payroll, or general document editing - use for Truss project, task, and contact management only.

## Capabilities

- Create and update projects with custom statuses and metadata fields
- Assign and update tasks tied to specific projects and users
- Search contacts by name or attribute and retrieve a contact-picker dropdown
- Look up projects by idempotency key to prevent duplicate creation
- List projects filtered by metadata key for downstream reporting
- Transition project status with the dedicated update_status endpoint
- Manage drive folders and entity records for collaborative file workflows

## Use cases

### Sync Project Data with External Tools

Operations teams running Truss alongside CRMs, billing tools, or BI dashboards need project records to flow both ways. The Truss API exposes list and update on projects, plus idempotency-key lookup so a sync job can safely re-run without creating duplicates. Pair this with the metadata-key list endpoint to slice projects by external identifier.

Example prompt: List projects with metadata key 'crm_id=987', then update each project's status field to 'in-review'.

### Automated Task Assignment

When a new client signs a contract or a deal closes in another system, a downstream workflow can create the associated tasks in Truss automatically. The tasks resource accepts a project id, owner, and due date so the agent or workflow tool spins up the full task list without manual entry. The contact-search endpoint resolves owner names to user records first.

Example prompt: For each task in the kickoff template, create it in project 555 with the matching owner resolved via `/contacts/search.`

### Contact Search and Picker UIs

Internal tools that mirror the Truss contact list use GET `/contacts/search` for autocomplete and GET `/contacts/dropdown` for the standard picker. This avoids loading the full contact list into the browser and keeps response sizes small for high-traffic admin tools.

Example prompt: Call GET `/contacts/search` with query 'acme' and return the first 10 matching contacts.

### AI Agent Project Operations

AI agents triaging email or chat into Truss can create projects, attach contacts, and update statuses without UI navigation. Through Jentic the agent finds the right operation by intent ('create a project' or 'update project status'), loads its schema, and executes - Truss bearer tokens stay in your Jentic One instance rather than reaching the agent context.

Example prompt: Create a project named 'Acme Q2 Onboarding' with idempotency key 'acme-q2-2026' and assign the contact id returned by `/contacts/search.`

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/projects` | Create a new project |
| GET | `/projects/get_by_idempotency_key` | Look up a project by idempotency key |
| POST | `/projects/{id}/update_status` | Change project status |
| GET | `/projects/list_by_metadata_key` | List projects filtered by metadata key |
| GET | `/contacts/search` | Search contacts by query |
| GET | `/contacts/dropdown` | Get contact picker dropdown payload |

## Key resources

- **Projects** — Create, retrieve, update, and transition status on projects
- **Tasks** — Create and assign tasks tied to projects
- **Contacts** — Search, list, and retrieve contact records and the picker dropdown
- **Users** — Manage Truss user records and permissions
- **Entities** — Work with shared entity records used across projects
- **Drive Folders** — Manage drive folder structures attached to projects

## Why Jentic

- **Setup:** Wiring the Truss API by hand means attaching your bearer token from the Integrations menu, targeting the app2.gettruss.io host, and threading idempotency keys through project creation yourself. Through Jentic you install once, import the Truss API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Truss puts the project id in the URL path (`/projects/{id}/update_status`), so a rule can pin your agent to one project for status updates. You choose the operations it may call, so wider ones like creating projects or searching contacts are not included unless you add them.
- **Credential handling:** Your Truss bearer token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a project' or 'update a project status', and Jentic returns the matching Truss operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Asana** — Asana is a general project management platform; Truss is positioned for file-collection-heavy workflows
- **Notion** — Notion combines documents and project tracking; Truss focuses on structured project records and tasks
- **HubSpot CRM Contacts** — HubSpot stores customer records that often map to Truss contacts and projects

## FAQ

### What authentication does the Truss API use?

Truss uses HTTP bearer authentication - clients send Authorization: Bearer <token> on every request. Through Jentic this token is stored encrypted in the vault and the agent only receives a scoped capability to invoke specific Truss operations.

### Can I create a new project with the Truss API?

Yes. POST /projects accepts the project payload and returns the created record. Pair this with GET `/projects/get_by_idempotency_key` on retry so the same idempotency key always resolves to one project, never a duplicate.

### What are the rate limits for the Truss API?

The spec does not declare explicit limits. Production integrations should respect 429 responses with backoff and avoid tight loops over /projects or /contacts; cache the contact dropdown payload where possible since it is a heavy response.

### How do I update a project status with Truss through Jentic?

Search Jentic for 'change truss project status'. Jentic returns POST `/projects/{id}/update_status` with its input schema; load it, supply the project id and target status, and execute. The response confirms the new status.

### Can I search Truss contacts by name?

Yes. GET `/contacts/search` accepts a query string and returns matching contact records. For lighter UI use cases GET `/contacts/dropdown` returns the picker-ready list without full contact bodies.

### Can I limit what my agent is allowed to do with the Truss API?

Yes. Because you self-host Jentic One, your own rules decide which Truss operations and credentials the agent may use. Since Truss puts the project id in the URL path, such as POST `/projects/{id}/update_status`, you can pin the agent to status updates on a single project and leave wider operations like creating projects or searching contacts out of its reach. Only the operations you explicitly allow are callable, and your bearer token is injected at execution time rather than handed to the agent.