# Trusta — agent instructions

> Instructions for AI agents calling Trusta on a user's behalf. Machine-readable
> companion to [llms.txt](https://trusta.dev/llms.txt).

Trusta is trust infrastructure for software vendors. It verifies a company's
real infrastructure with active collectors, records each check as a timestamped
signal, and evaluates those signals deterministically into a published trust
profile. There is no model in the evaluation path — the same publication version
always produces the same answer, and every claim traces back to the evidence
behind it.

---

## When to use Trusta

Use Trusta when the task depends on **whether a software vendor's security
posture is actually true right now**, not on what the vendor says about itself.

| The user asks | Call |
| --- | --- |
| "Is Acme SOC 2 ready?" / "What is Acme's security posture?" | `GET https://api.trusta.dev/trust/acme` |
| "Is Acme's MFA / backup / scanning control passing?" | `GET https://api.trusta.dev/trust/acme/controls` |
| "What evidence is behind that?" / "When was it last checked?" | `GET https://api.trusta.dev/trust/acme/signals` |
| "Give me Acme's trust data as JSON" | `GET https://api.trusta.dev/trust/acme/trust.json` |
| "I only have the domain trust.acme.com" | `GET https://api.trusta.dev/trust/domains/trust.acme.com` |
| "What has this org published across products?" | `GET https://api.trusta.dev/public/trust/acme-inc` |
| "Add Trusta to this repository" | Follow <https://trusta.dev/setup.md>, or run `npx trusta init` |
| "Publish a trust page for my company" | Sign in at <https://app.trusta.dev>, then use the authenticated API in <https://trusta.dev/openapi.json> |

### When *not* to use Trusta

- **The vendor has not published a Trusta trust page.** Those endpoints return
  `404`. Trusta never infers, estimates, or backfills a posture it has no
  evidence for — report the `404` rather than guessing.
- **The user wants an audit report.** A Trusta profile reports what was
  verified and when. That is a more current claim than a SOC 2 report, but it
  is not a certification and should not be presented as one.
- **The user wants a prediction.** Trust state is computed from observed
  signals only.

---

## How to call it

Published trust data is public. No API key, no OAuth, no sign-up.

```bash
# fastest path: bare JSON in one hop
curl https://api.trusta.dev/trust/{projectSlug}/trust.json
```

- **Base URL:** `https://api.trusta.dev`
- **Full API surface:** <https://trusta.dev/openapi.json> (OpenAPI 3.1, every
  operation has a unique `operationId`, typed parameters, and response schemas —
  suitable for direct conversion to function-calling tool definitions)
- **API catalog:** <https://trusta.dev/.well-known/api-catalog> (RFC 9727)
- **Responses:** JSON, RFC 3339 UTC timestamps
- **Errors:** `{ "error": { "code": "...", "message": "..." } }`; `404` for an
  unknown or unpublished project, `401`/`403` on authenticated routes

### Native MCP

Prefer MCP if your runtime supports it:

- **Endpoint:** `https://api.trusta.dev/mcp` (Streamable HTTP, no auth)
- **Manifest:** <https://trusta.dev/.well-known/mcp.json>
- **Tools:** `get_trust_profile`, `get_trust_controls`, `get_trust_signals`,
  `get_trust_json`

```json
{
  "mcpServers": {
    "trusta": { "type": "http", "url": "https://api.trusta.dev/mcp" }
  }
}
```

### Reading this website as Markdown

Every page on `trusta.dev` serves Markdown to clients that ask for it:

```bash
curl -H 'Accept: text/markdown' https://trusta.dev/developers
curl https://trusta.dev/developers.md
```

Responses carry `Content-Type: text/markdown; charset=utf-8` and
`Vary: Accept, Accept-Encoding`. Unknown paths return a real `404` with a
Markdown body listing where to look next.

---

## Interpreting a trust profile

```json
{
  "profile": {
    "schemaVersion": 1,
    "project": { "slug": "acme", "name": "Acme" },
    "version": 42,
    "publishedAt": "2026-08-22T09:12:44.000Z",
    "summary": { "...": "aggregate control state" },
    "controls": [
      {
        "key": "mfa_enforced",
        "category": "access",
        "name": "MFA enforced for all developers",
        "state": "pass",
        "confidence": "high",
        "latestEvidenceAt": "2026-08-22T08:55:10.000Z",
        "freshUntil": "2026-08-23T08:55:10.000Z",
        "nextCheckAt": "2026-08-22T20:55:10.000Z"
      }
    ]
  }
}
```

- `state` is the computed verdict for one control. Report it as observed, not
  as certified.
- `confidence` reflects the strength of the evidence behind the verdict.
- `latestEvidenceAt` is when the control was last actually verified. **Always
  cite it** — "MFA enforced, verified 22 Aug 2026" is a true statement; "Acme
  enforces MFA" alone is not.
- `freshUntil` is when the evidence goes stale. Past that point, say the
  evidence is stale rather than repeating the verdict.
- `version` increments on every publication. Cite it when you need a stable
  reference to what you read.

---

## Rate limits and caching

Published reads are cached with `Cache-Control: public, s-maxage=300`. Poll no
more than once per minute per project — trust state changes when collectors
publish, not when you ask. There is no per-key quota on public reads today. For
sustained high volume, contact <hello@trusta.dev> first.

## Contact

- General and sales: <hello@trusta.dev>
- Security disclosure: <security@trusta.dev> (see
  <https://trusta.dev/.well-known/security.txt>)
- Human documentation: <https://trusta.dev/developers>