{ "openapi": "3.1.0", "info": { "title": "Trusta API", "version": "1.0.0", "summary": "Live, verifiable trust data for software vendors — computed from real infrastructure, not self-reported.", "description": "Trusta replaces static compliance documents with live, computed trust. Collectors actively verify a vendor's infrastructure, produce signals, and those signals are evaluated deterministically into a published trust profile.\n\nThe `/trust/*` and `/public/*` endpoints are public and need no authentication — an agent can read any published vendor trust profile directly. Everything else manages a workspace and requires a bearer token: a Cognito access token for human users, or a collector secret for machine clients.\n\nStart with `GET /trust/{projectSlug}` to read a vendor trust profile, or `GET /trust/domains/{domain}` when you only know the vendor domain.", "termsOfService": "https://trusta.dev/terms", "contact": { "name": "Trusta Support", "email": "hello@trusta.dev", "url": "https://trusta.dev/contact" } }, "externalDocs": { "description": "Trusta developer portal", "url": "https://trusta.dev/developers" }, "servers": [ { "url": "https://api.trusta.dev", "description": "Production" }, { "url": "http://localhost:4000", "description": "Local development" } ], "tags": [ { "name": "Public trust", "description": "Unauthenticated reads of published vendor trust profiles, controls, and signals." }, { "name": "Service", "description": "Liveness and machine-readable service description." }, { "name": "Identity", "description": "The authenticated caller and their organization memberships." }, { "name": "Organizations", "description": "Organization structure, membership, and projects." }, { "name": "Projects", "description": "Project metadata, controls, evaluations, and publishing." }, { "name": "Domains", "description": "Custom domain registration and verification for trust pages." }, { "name": "Collectors", "description": "Machine principals that actively verify infrastructure." }, { "name": "Evidence", "description": "Evidence metadata ingest and artifact references." }, { "name": "Admin", "description": "Platform administration." } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "ApiError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "User": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "cognitoSub": { "type": "string" }, "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "cognitoSub", "email", "name", "createdAt", "updatedAt" ] }, "Organization": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "slug", "createdAt", "updatedAt" ] }, "OrganizationSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "member" ] } }, "required": [ "id", "name", "slug", "role" ] }, "OrganizationMember": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "userId": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "owner", "member" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "userId", "role", "createdAt" ] }, "OrganizationMemberSummary": { "type": "object", "properties": { "membership": { "$ref": "#/components/schemas/OrganizationMember" }, "user": { "$ref": "#/components/schemas/User" } }, "required": [ "membership", "user" ] }, "Project": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "hostedSubdomain": { "type": [ "string", "null" ] }, "visibility": { "type": "string", "enum": [ "private", "public" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "name", "slug", "hostedSubdomain", "visibility", "createdAt", "updatedAt" ] }, "ProjectDomain": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "domain": { "type": "string" }, "verificationStatus": { "type": "string", "enum": [ "pending", "verified" ] }, "verificationMethod": { "type": "string", "enum": [ "dns_txt" ] }, "verificationToken": { "type": "string" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "projectId", "domain", "verificationStatus", "verificationMethod", "verificationToken", "verifiedAt", "lastCheckedAt", "createdAt", "updatedAt" ] }, "ProjectDomainVerificationInstructions": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "dns_txt" ] }, "recordName": { "type": "string" }, "recordType": { "type": "string", "enum": [ "TXT" ] }, "recordValue": { "type": "string" } }, "required": [ "method", "recordName", "recordType", "recordValue" ] }, "ProjectDomainSummary": { "type": "object", "properties": { "domain": { "$ref": "#/components/schemas/ProjectDomain" }, "instructions": { "$ref": "#/components/schemas/ProjectDomainVerificationInstructions" } }, "required": [ "domain", "instructions" ] }, "CollectorPrincipal": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "cli" ] }, "status": { "type": "string", "enum": [ "active", "revoked" ] }, "allowedActions": { "type": "array", "items": { "type": "string" } }, "lastSeenAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdByUserId": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "organizationId", "projectId", "name", "type", "status", "allowedActions", "lastSeenAt", "createdByUserId", "createdAt", "revokedAt" ] }, "EvidenceCollectorSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "EvidenceRecordSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "collectorPrincipalId": { "type": "string", "format": "uuid" }, "collector": { "$ref": "#/components/schemas/EvidenceCollectorSummary" }, "evidenceType": { "type": "string", "enum": [ "build_provenance", "dependency_inventory", "deployment_snapshot", "policy_result", "sbom", "vulnerability_scan" ] }, "sourceType": { "type": "string", "enum": [ "aws", "collector", "custom", "github_actions", "kubernetes", "terraform" ] }, "sourceRef": { "type": "string" }, "payloadS3Key": { "type": "string" }, "checksum": { "type": "string" }, "observedAt": { "type": "string", "format": "date-time" }, "receivedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "projectId", "collectorPrincipalId", "collector", "evidenceType", "sourceType", "sourceRef", "payloadS3Key", "checksum", "observedAt", "receivedAt" ] }, "EvidenceRecordResponse": { "type": "object", "properties": { "record": { "$ref": "#/components/schemas/EvidenceRecordSummary" } }, "required": [ "record" ] }, "EvidenceRecordListResponse": { "type": "object", "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/EvidenceRecordSummary" } } }, "required": [ "records" ] }, "FreshnessPolicy": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "none" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "time_window" ] }, "windowSeconds": { "type": "integer", "minimum": 1 } }, "required": [ "kind", "windowSeconds" ] } ] }, "DegradationPolicy": { "type": "object", "properties": { "staleAfterSeconds": { "type": [ "integer", "null" ], "minimum": 0 }, "degradedAfterSeconds": { "type": [ "integer", "null" ], "minimum": 0 } }, "required": [ "staleAfterSeconds", "degradedAfterSeconds" ] }, "TrustControl": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "category": { "type": "string", "enum": [ "collector", "evidence" ] }, "publicName": { "type": "string" }, "freshnessPolicyJson": { "$ref": "#/components/schemas/FreshnessPolicy" }, "degradationPolicyJson": { "$ref": "#/components/schemas/DegradationPolicy" }, "enabled": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "key", "category", "publicName", "freshnessPolicyJson", "degradationPolicyJson", "enabled", "createdAt" ] }, "TrustControlListResponse": { "type": "object", "properties": { "controls": { "type": "array", "items": { "$ref": "#/components/schemas/TrustControl" } } }, "required": [ "controls" ] }, "ControlEvaluationSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "trustControlId": { "type": "string", "format": "uuid" }, "state": { "type": "string", "enum": [ "unknown", "pass", "fail", "stale", "degraded" ] }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "latestEvidenceRecordId": { "type": [ "string", "null" ], "format": "uuid" }, "latestEvidenceAt": { "type": [ "string", "null" ], "format": "date-time" }, "freshUntil": { "type": [ "string", "null" ], "format": "date-time" }, "nextCheckAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "control": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "category": { "type": "string", "enum": [ "collector", "evidence" ] }, "publicName": { "type": "string" }, "enabled": { "type": "boolean" } }, "required": [ "id", "key", "category", "publicName", "enabled" ] } }, "required": [ "id", "projectId", "trustControlId", "state", "confidence", "latestEvidenceRecordId", "latestEvidenceAt", "freshUntil", "nextCheckAt", "updatedAt", "control" ] }, "ControlEvaluationListResponse": { "type": "object", "properties": { "evaluations": { "type": "array", "items": { "$ref": "#/components/schemas/ControlEvaluationSummary" } } }, "required": [ "evaluations" ] }, "PublishJob": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "requested", "running", "completed", "failed" ] }, "reason": { "type": [ "string", "null" ] }, "requestedAt": { "type": "string", "format": "date-time" }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "projectId", "status", "reason", "requestedAt", "startedAt", "completedAt" ] }, "PublishedProfile": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1 }, "artifactS3Key": { "type": "string" }, "publishedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "projectId", "version", "artifactS3Key", "publishedAt" ] }, "PublishProjectResponse": { "type": "object", "properties": { "job": { "$ref": "#/components/schemas/PublishJob" }, "publishedProfile": { "$ref": "#/components/schemas/PublishedProfile" } }, "required": [ "job", "publishedProfile" ] }, "PublishedProfileResponse": { "type": "object", "properties": { "publishedProfile": { "$ref": "#/components/schemas/PublishedProfile" } }, "required": [ "publishedProfile" ] }, "PublishedTrustProject": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "hostedSubdomain": { "type": [ "string", "null" ] } }, "required": [ "slug", "name", "hostedSubdomain" ] }, "PublishedTrustSummary": { "type": "object", "properties": { "overallState": { "type": "string", "enum": [ "unknown", "pass", "fail", "stale", "degraded" ] }, "totalControls": { "type": "integer", "minimum": 0 }, "passCount": { "type": "integer", "minimum": 0 }, "failCount": { "type": "integer", "minimum": 0 }, "staleCount": { "type": "integer", "minimum": 0 }, "degradedCount": { "type": "integer", "minimum": 0 }, "unknownCount": { "type": "integer", "minimum": 0 } }, "required": [ "overallState", "totalControls", "passCount", "failCount", "staleCount", "degradedCount", "unknownCount" ] }, "PublishedTrustControl": { "type": "object", "properties": { "key": { "type": "string" }, "category": { "type": "string", "enum": [ "collector", "evidence" ] }, "name": { "type": "string" }, "state": { "type": "string", "enum": [ "unknown", "pass", "fail", "stale", "degraded" ] }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "latestEvidenceAt": { "type": [ "string", "null" ], "format": "date-time" }, "freshUntil": { "type": [ "string", "null" ], "format": "date-time" }, "nextCheckAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "key", "category", "name", "state", "confidence", "latestEvidenceAt", "freshUntil", "nextCheckAt" ] }, "HealthStatus": { "type": "object", "description": "Liveness result for the Trusta API.", "properties": { "status": { "type": "string", "enum": [ "ok" ] } }, "required": [ "status" ] }, "TrustSignalGroup": { "type": "object", "description": "One detected capability group and the concrete tools or providers behind it.", "properties": { "detected": { "type": "boolean" }, "tools": { "type": "array", "items": { "type": "string" } }, "providers": { "type": "array", "items": { "type": "string" } } }, "required": [ "detected" ] }, "TrustSignalDetection": { "type": "object", "description": "The most recent signal detection for a project. Signals are raw data points produced by collectors — the inputs to deterministic trust evaluation, not the verdict itself.", "properties": { "detectedAt": { "type": "string", "format": "date-time" }, "commitSha": { "type": "string" }, "ciCd": { "$ref": "#/components/schemas/TrustSignalGroup" }, "monitoring": { "$ref": "#/components/schemas/TrustSignalGroup" }, "authProvider": { "$ref": "#/components/schemas/TrustSignalGroup" }, "cloudProvider": { "$ref": "#/components/schemas/TrustSignalGroup" }, "securityContact": { "type": "object", "properties": { "detected": { "type": "boolean" }, "email": { "type": [ "string", "null" ], "format": "email" } }, "required": [ "detected", "email" ] } }, "required": [ "detectedAt", "commitSha", "ciCd", "monitoring", "authProvider", "cloudProvider", "securityContact" ] }, "TrustSignalsResponse": { "type": "object", "properties": { "signals": { "oneOf": [ { "$ref": "#/components/schemas/TrustSignalDetection" }, { "type": "null" } ], "description": "Null when the project has never submitted a signal detection." } }, "required": [ "signals" ] }, "PublishedTrustProfile": { "type": "object", "properties": { "schemaVersion": { "type": "integer", "enum": [ 1 ] }, "project": { "$ref": "#/components/schemas/PublishedTrustProject" }, "version": { "type": "integer", "minimum": 1 }, "publishedAt": { "type": "string", "format": "date-time" }, "summary": { "$ref": "#/components/schemas/PublishedTrustSummary" }, "controls": { "type": "array", "items": { "$ref": "#/components/schemas/PublishedTrustControl" } } }, "required": [ "schemaVersion", "project", "version", "publishedAt", "summary", "controls" ] }, "PublishedTrustProfileResponse": { "type": "object", "properties": { "profile": { "$ref": "#/components/schemas/PublishedTrustProfile" } }, "required": [ "profile" ] }, "PublishedTrustControlsResponse": { "type": "object", "properties": { "project": { "$ref": "#/components/schemas/PublishedTrustProject" }, "version": { "type": "integer", "minimum": 1 }, "publishedAt": { "type": "string", "format": "date-time" }, "summary": { "$ref": "#/components/schemas/PublishedTrustSummary" }, "controls": { "type": "array", "items": { "$ref": "#/components/schemas/PublishedTrustControl" } } }, "required": [ "project", "version", "publishedAt", "summary", "controls" ] }, "ProjectDomainListResponse": { "type": "object", "properties": { "project": { "$ref": "#/components/schemas/Project" }, "domains": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectDomainSummary" } } }, "required": [ "project", "domains" ] }, "ProjectDomainResponse": { "type": "object", "properties": { "project": { "$ref": "#/components/schemas/Project" }, "domain": { "$ref": "#/components/schemas/ProjectDomainSummary" } }, "required": [ "project", "domain" ] }, "CreateProjectDomainRequest": { "type": "object", "properties": { "domain": { "type": "string" } }, "required": [ "domain" ] }, "IngestEvidenceRequest": { "type": "object", "properties": { "projectId": { "type": "string", "format": "uuid" }, "evidenceType": { "type": "string", "enum": [ "build_provenance", "dependency_inventory", "deployment_snapshot", "policy_result", "sbom", "vulnerability_scan" ] }, "sourceType": { "type": "string", "enum": [ "aws", "collector", "custom", "github_actions", "kubernetes", "terraform" ] }, "sourceRef": { "type": "string" }, "observedAt": { "type": "string", "format": "date-time" }, "payload": { "type": "object", "additionalProperties": true } }, "required": [ "projectId", "evidenceType", "sourceType", "sourceRef", "observedAt", "payload" ] }, "BatchIngestEvidenceRequest": { "type": "object", "properties": { "projectId": { "type": "string", "format": "uuid" }, "records": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "properties": { "evidenceType": { "type": "string", "enum": [ "build_provenance", "dependency_inventory", "deployment_snapshot", "policy_result", "sbom", "vulnerability_scan" ] }, "sourceType": { "type": "string", "enum": [ "aws", "collector", "custom", "github_actions", "kubernetes", "terraform" ] }, "sourceRef": { "type": "string" }, "observedAt": { "type": "string", "format": "date-time" }, "payload": { "type": "object", "additionalProperties": true } }, "required": [ "evidenceType", "sourceType", "sourceRef", "observedAt", "payload" ] } } }, "required": [ "projectId", "records" ] }, "CollectorWithSecretResponse": { "type": "object", "properties": { "collector": { "$ref": "#/components/schemas/CollectorPrincipal" }, "secret": { "type": "object", "properties": { "value": { "type": "string" }, "prefix": { "type": "string" } }, "required": [ "value", "prefix" ] } }, "required": [ "collector", "secret" ] }, "CollectorListResponse": { "type": "object", "properties": { "collectors": { "type": "array", "items": { "$ref": "#/components/schemas/CollectorPrincipal" } } }, "required": [ "collectors" ] }, "CollectorResponse": { "type": "object", "properties": { "collector": { "$ref": "#/components/schemas/CollectorPrincipal" } }, "required": [ "collector" ] }, "OrganizationMembersResponse": { "type": "object", "properties": { "organization": { "$ref": "#/components/schemas/Organization" }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationMemberSummary" } } }, "required": [ "organization", "members" ] }, "BootstrapWorkspaceRequest": { "type": "object", "properties": { "workspaceName": { "type": "string" }, "workspaceSlug": { "type": "string" }, "projectName": { "type": "string" }, "projectSlug": { "type": "string" }, "projectHostedSubdomain": { "type": [ "string", "null" ] }, "projectVisibility": { "type": "string", "enum": [ "private", "public" ] } }, "required": [ "workspaceName", "projectName" ] }, "BootstrapWorkspaceResponse": { "type": "object", "properties": { "organization": { "$ref": "#/components/schemas/Organization" }, "project": { "$ref": "#/components/schemas/Project" } }, "required": [ "organization", "project" ] } } }, "paths": { "/health": { "get": { "tags": [ "Service" ], "summary": "Check API liveness", "description": "Unauthenticated liveness probe. Returns `{\"status\":\"ok\"}` when the API is serving traffic. Use this to confirm reachability before running a longer integration.", "operationId": "getHealth", "responses": { "200": { "description": "API is serving traffic", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthStatus" } } } } } } }, "/openapi.json": { "get": { "tags": [ "Service" ], "summary": "Get this OpenAPI specification", "description": "Unauthenticated. Returns the full OpenAPI 3.1 description of this API, so an agent can discover the surface without out-of-band documentation. The same document is mirrored at https://trusta.dev/openapi.json.", "operationId": "getOpenApiSpec", "responses": { "200": { "description": "OpenAPI 3.1 document returned", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/trust/{projectSlug}/trust.json": { "get": { "tags": [ "Public trust" ], "summary": "Get the machine-readable trust state for a project slug", "description": "Unauthenticated. Returns the published trust profile as a bare JSON document with no response envelope, suitable for direct machine consumption and caching. Prefer this over `GET /trust/{projectSlug}` when you want the profile itself rather than a wrapped response.", "operationId": "getTrustJson", "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "description": "The Trusta project slug identifying the vendor, for example `acme`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Machine-readable published trust state returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishedTrustProfile" } } } }, "404": { "description": "Project slug not found or project has not been published" } } } }, "/trust/{projectSlug}/signals": { "get": { "tags": [ "Public trust" ], "summary": "Get the latest trust signals for a project slug", "description": "Unauthenticated. Returns the most recent signal detection for a project — the raw data points collectors observed, with the commit and timestamp they were observed at. Use this when you need the evidence behind a trust state rather than the state itself.", "operationId": "getPublishedTrustSignals", "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "description": "The Trusta project slug identifying the vendor, for example `acme`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Latest signal detection returned, or null when none exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrustSignalsResponse" } } } }, "404": { "description": "Project slug not found" } } } }, "/trust/{projectSlug}/setup.md": { "get": { "tags": [ "Public trust" ], "summary": "Get the agent-readable setup guide for a project", "description": "Unauthenticated. Returns a Markdown setup guide tailored to one project, written for coding agents to follow when wiring Trusta into a repository.", "operationId": "getProjectSetupGuide", "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "description": "The Trusta project slug identifying the vendor, for example `acme`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Markdown setup guide returned", "content": { "text/markdown": { "schema": { "type": "string" } } } }, "404": { "description": "Project slug not found" } } } }, "/me": { "get": { "summary": "Get the authenticated user profile", "description": "Return the authenticated human user together with the organizations they belong to. Requires a Cognito bearer token. Use this to resolve the caller's identity and available organization scopes before making any other authenticated call.", "operationId": "getMe", "tags": [ "Identity" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Current user profile and memberships" }, "401": { "description": "Authentication failed" } } } }, "/onboarding/bootstrap": { "post": { "summary": "Bootstrap the first workspace and project for a new user", "description": "Create the first organization and project for a newly signed-up user in a single call. Idempotent per user: returns 409 when the caller already owns a workspace.", "operationId": "bootstrapWorkspace", "tags": [ "Organizations" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Workspace bootstrap completed" }, "409": { "description": "Workspace bootstrap is no longer allowed" } } } }, "/organizations": { "post": { "summary": "Create an organization", "description": "Create an organization owned by the authenticated user. Organizations are the billing and membership boundary; projects live inside them.", "operationId": "createOrganization", "tags": [ "Organizations" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Organization created" } } } }, "/organizations/{organizationId}": { "get": { "summary": "Get an organization", "description": "Read a single organization the caller is a member of. Returns the organization name, slug, and timestamps.", "operationId": "getOrganization", "tags": [ "Organizations" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "organizationId", "description": "Identifier of the organization the caller is a member of.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Organization details" } } } }, "/organizations/{organizationId}/projects": { "get": { "summary": "List projects in an organization", "description": "List every project inside an organization the caller is a member of. Use this to discover project ids and slugs for project-scoped calls.", "operationId": "listOrganizationProjects", "tags": [ "Organizations" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "organizationId", "description": "Identifier of the organization the caller is a member of.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Projects in the organization" } } } }, "/organizations/{organizationId}/members": { "get": { "summary": "List members in an organization", "description": "List the members of an organization together with their role. Only members of the organization may read this.", "operationId": "listOrganizationMembers", "tags": [ "Organizations" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "organizationId", "description": "Identifier of the organization the caller is a member of.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Members in the organization" } } } }, "/projects": { "post": { "summary": "Create a project", "description": "Create a project inside an organization the caller belongs to. A project is the unit that owns collectors, evidence, controls, and one public trust page.", "operationId": "createProject", "tags": [ "Projects" ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Project created" } } } }, "/projects/{id}": { "get": { "summary": "Get a project", "description": "Read a single project by id, including its slug and owning organization. Use the slug for public trust endpoints.", "operationId": "getProject", "tags": [ "Projects" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "description": "Identifier of the resource the request applies to.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Project details" } } }, "patch": { "summary": "Update a project", "description": "Update mutable project metadata such as its display name. Does not change the slug, which is fixed at creation because published trust page URLs depend on it.", "operationId": "updateProject", "tags": [ "Projects" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "description": "Identifier of the resource the request applies to.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Project updated" } } } }, "/projects/{id}/controls": { "get": { "summary": "List trust controls for a project", "description": "List the controls configured for a project together with their current deterministic evaluation state. This is the internal, pre- publication view; use the public trust endpoints for what buyers see.", "operationId": "listProjectControls", "tags": [ "Projects" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "description": "Identifier of the resource the request applies to.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Trust control catalog metadata listed" }, "401": { "description": "Authentication failed" }, "403": { "description": "Project access denied" } } } }, "/projects/{id}/evaluations": { "get": { "summary": "List persisted control evaluations for a project", "description": "List the stored control evaluations for a project. Every evaluation records the signals it was computed from, so the result is auditable rather than inferred.", "operationId": "listProjectEvaluations", "tags": [ "Projects" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "description": "Identifier of the resource the request applies to.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Control evaluations listed" }, "401": { "description": "Authentication failed" }, "403": { "description": "Project access denied" } } } }, "/projects/{id}/evaluations/recompute": { "post": { "summary": "Recompute all deterministic control evaluations for a project", "description": "Human-auth protected recompute path. Re-evaluates the enabled control catalog against current project evidence and collector metadata, then persists evaluation results deterministically.", "operationId": "recomputeProjectEvaluations", "tags": [ "Projects" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "description": "Identifier of the resource the request applies to.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Project evaluations recomputed and persisted" }, "401": { "description": "Authentication failed" }, "403": { "description": "Project access denied" } } } }, "/projects/{id}/publish": { "post": { "summary": "Publish current project metadata and evaluation state", "description": "Human-auth protected synchronous publish flow. Creates a publish job, writes deterministic artifact metadata, persists the next published profile version, and finalizes the job status.", "operationId": "publishProject", "tags": [ "Projects" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "description": "Identifier of the resource the request applies to.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Publish job completed and latest published profile metadata persisted" }, "401": { "description": "Authentication failed" }, "403": { "description": "Project access denied" }, "500": { "description": "Publish flow failed after job creation" } } } }, "/projects/{id}/published-profile": { "get": { "summary": "Get the latest published profile metadata for a project", "description": "Read the currently published trust profile for a project from the operator side, including publication version and timestamp. Returns 404 when the project has never been published.", "operationId": "getPublishedProfile", "tags": [ "Projects" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "description": "Identifier of the resource the request applies to.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Latest published profile metadata returned" }, "401": { "description": "Authentication failed" }, "403": { "description": "Project access denied" }, "404": { "description": "No published profile exists for the project" } } } }, "/projects/{id}/domains": { "get": { "summary": "List custom domains for a project", "description": "List custom domains registered against a project and the stage each one has reached in DNS verification, certificate issuance, and CDN activation.", "operationId": "listProjectDomains", "tags": [ "Domains" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "description": "Identifier of the resource the request applies to.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Project domains listed" }, "401": { "description": "Authentication failed" }, "403": { "description": "Project access denied" } } }, "post": { "summary": "Add a custom domain to a project", "description": "Register a custom domain for a project trust page. Returns the DNS TXT record the caller must publish at _trusta. before verification can succeed.", "operationId": "createProjectDomain", "tags": [ "Domains" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "description": "Identifier of the resource the request applies to.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Project domain created with verification instructions" }, "401": { "description": "Authentication failed" }, "403": { "description": "Project access denied" }, "409": { "description": "Domain is already assigned to another project" } } } }, "/projects/{projectId}/domains/{domainId}/verify": { "post": { "summary": "Verify a project custom domain via DNS TXT", "description": "Check the _trusta. DNS TXT record for a registered domain and, on success, start automated certificate provisioning and CDN configuration.", "operationId": "verifyProjectDomain", "tags": [ "Domains" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "projectId", "description": "Identifier of the project the request applies to.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "domainId", "description": "Identifier of the custom domain registration.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Project domain verification checked" }, "401": { "description": "Authentication failed" }, "403": { "description": "Project access denied" }, "404": { "description": "Project domain not found" } } } }, "/projects/{projectId}/domains/{domainId}": { "delete": { "summary": "Remove a custom domain from a project", "description": "Remove a custom domain from a project. The canonical /trust/{projectSlug} route keeps serving the published trust page.", "operationId": "deleteProjectDomain", "tags": [ "Domains" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "projectId", "description": "Identifier of the project the request applies to.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "domainId", "description": "Identifier of the custom domain registration.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Project domain removed" }, "401": { "description": "Authentication failed" }, "403": { "description": "Project access denied" }, "404": { "description": "Project domain not found" } } } }, "/trust/{projectSlug}": { "get": { "summary": "Get the latest published trust profile for a project slug", "description": "Public published-read endpoint. Resolves the latest published profile metadata, reads the stored published artifact, and returns only the stable public-safe contract.", "operationId": "getPublishedTrust", "tags": [ "Public trust" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "description": "The Trusta project slug identifying the vendor, for example `acme`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Published trust profile returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishedTrustProfileResponse" } } } }, "404": { "description": "Project slug not found or project has not been published" } } } }, "/projects/{projectId}/classification": { "get": { "summary": "Read a project classification and its contradictions", "description": "What the project declares itself to be, plus any place the evidence disagrees. Served rather than computed by callers so the rule for what counts as a contradiction lives in one place.", "operationId": "getProjectClassification", "tags": [ "Projects" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "projectId", "description": "Identifier of the project the request applies to.", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Classification returned" }, "401": { "description": "Authentication failed" }, "403": { "description": "Project access denied" }, "404": { "description": "Project not found" } } }, "post": { "summary": "Declare what a project is", "description": "Narrows which controls apply (ADR 0014). The request carries facets only — `declaredAt` and `mapVersion` are stamped by the server, so a vendor cannot make a narrowed control set look as though it were evaluated against rules that never existed. A declaration the evidence contradicts is stored and reported, not refused; evaluation ignores it until the disagreement is resolved.", "operationId": "declareProjectClassification", "tags": [ "Projects" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "projectId", "description": "Identifier of the project the request applies to.", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Classification stored" }, "401": { "description": "Authentication failed" }, "403": { "description": "Project access denied" }, "404": { "description": "Project not found" } } } }, "/admin/overview": { "get": { "summary": "Every organisation, project and user on the instance", "description": "Gated on the PLATFORM_ADMIN_EMAILS allowlist. Answers 404 rather than 403 to a caller who is not on it, so a signed-in customer probing the route learns nothing about whether it exists. An unset allowlist admits nobody.", "operationId": "getPlatformAdminOverview", "tags": [ "Admin" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Overview returned" }, "401": { "description": "Authentication failed" }, "404": { "description": "Not found, or caller is not an admin" } } } }, "/public/trust-location/{projectSlug}": { "get": { "summary": "Resolve a bare project slug to its organisation-scoped URL", "description": "Supports redirecting the retired single-segment trust URL. Only published projects resolve; an unpublished project answers the same 404 as an unknown slug.", "operationId": "getPublishedProjectLocation", "tags": [ "Public trust" ], "parameters": [ { "name": "projectSlug", "description": "The Trusta project slug identifying the vendor, for example `acme`.", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Organisation-scoped location returned" }, "404": { "description": "Project slug not found or not published" } } } }, "/public/trust/{orgSlug}": { "get": { "summary": "Get an organisation trust center", "description": "Public read of every published system belonging to an organisation. Unpublished projects are absent. The payload carries no organisation-level rollup — no score, no combined state — by design (ADR 0015); a reader that wants a total counts the systems array itself.", "operationId": "getOrganizationTrustCenter", "tags": [ "Public trust" ], "parameters": [ { "name": "orgSlug", "description": "The Trusta organization slug, for example `acme-inc`.", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Organisation trust center returned" }, "404": { "description": "Organisation slug not found" } } } }, "/public/trust/{orgSlug}/{projectSlug}": { "get": { "summary": "Get a published trust profile through its organisation", "description": "Public published-read endpoint scoped to the owning organisation. A project only answers under the organisation that owns it, so a request pairing an organisation with someone else’s project is a 404 rather than a page.", "operationId": "getOrganizationTrustProfile", "tags": [ "Public trust" ], "parameters": [ { "name": "orgSlug", "in": "path", "required": true, "description": "The Trusta organization slug, for example `acme-inc`.", "schema": { "type": "string" } }, { "name": "projectSlug", "in": "path", "required": true, "description": "The Trusta project slug identifying the vendor, for example `acme`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Published trust profile returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishedTrustProfileResponse" } } } }, "404": { "description": "Organisation not found, project not owned by that organisation, or project has not been published" } } } }, "/trust/domains/{domain}": { "get": { "summary": "Get the latest published trust profile for a verified custom domain", "description": "Public published-read endpoint that resolves a verified project domain, then serves the same stable published profile contract as the canonical project trust page.", "operationId": "getPublishedTrustByDomain", "tags": [ "Public trust" ], "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "The verified custom domain to resolve, for example `trust.acme.com`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Published trust profile returned for the verified domain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishedTrustProfileResponse" } } } }, "404": { "description": "Verified custom domain not found or project has not been published" } } } }, "/trust/{projectSlug}/controls": { "get": { "summary": "Get the published trust controls for a project slug", "description": "Public published-read endpoint returning only the controls section of the latest published artifact.", "operationId": "getPublishedTrustControls", "tags": [ "Public trust" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "description": "The Trusta project slug identifying the vendor, for example `acme`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Published controls returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishedTrustControlsResponse" } } } }, "404": { "description": "Project slug not found or project has not been published" } } } }, "/trust/{projectSlug}/profile": { "get": { "summary": "Get the published trust profile contract for a project slug", "description": "Public published-read endpoint returning the same stable contract as GET /trust/{projectSlug}.", "operationId": "getPublishedTrustProfile", "tags": [ "Public trust" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "description": "The Trusta project slug identifying the vendor, for example `acme`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Published trust profile returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishedTrustProfileResponse" } } } }, "404": { "description": "Project slug not found or project has not been published" } } } }, "/projects/{projectId}/collectors": { "get": { "summary": "List collectors for a project", "description": "List the collectors registered for a project. A collector is a machine principal that actively verifies infrastructure and submits evidence.", "operationId": "listProjectCollectors", "tags": [ "Collectors" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "projectId", "description": "Identifier of the project the request applies to.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Collectors listed" } } }, "post": { "summary": "Create a collector and reveal secret once", "description": "Register a new collector for a project and return its one-time plaintext secret. The secret is hashed at rest and cannot be read again — store it immediately.", "operationId": "createCollector", "tags": [ "Collectors" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "projectId", "description": "Identifier of the project the request applies to.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Collector created with one-time secret" } } } }, "/projects/{id}/evidence": { "get": { "summary": "List project evidence metadata", "description": "List evidence metadata records submitted for a project. Raw payloads live in object storage; this endpoint returns the metadata and artifact references only.", "operationId": "listProjectEvidence", "tags": [ "Evidence" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "description": "Identifier of the resource the request applies to.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Evidence metadata listed" }, "401": { "description": "Authentication failed" }, "403": { "description": "Project access denied" } } } }, "/collectors/{id}/rotate-secret": { "post": { "summary": "Rotate collector secret", "description": "Issue a new secret for an existing collector and invalidate the previous one. Returns the new plaintext secret exactly once.", "operationId": "rotateCollectorSecret", "tags": [ "Collectors" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "description": "Identifier of the resource the request applies to.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Collector secret rotated and revealed once" } } } }, "/collectors/{id}/revoke": { "post": { "summary": "Revoke collector", "description": "Permanently revoke a collector. Revoked collectors can no longer authenticate or submit evidence, and their past evidence stays in the audit trail.", "operationId": "revokeCollector", "tags": [ "Collectors" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "description": "Identifier of the resource the request applies to.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Collector revoked" } } } }, "/collectors/{id}/heartbeat": { "post": { "summary": "Collector heartbeat", "description": "Record a liveness heartbeat for the authenticated collector. Controls that depend on continuous verification go stale when heartbeats stop arriving.", "operationId": "collectorHeartbeat", "tags": [ "Collectors" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "description": "Identifier of the resource the request applies to.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Heartbeat accepted" }, "401": { "description": "Machine authentication failed" } } } }, "/ingest/evidence": { "post": { "summary": "Ingest a single evidence payload", "description": "Submit a single evidence record as an authenticated collector. The metadata is persisted relationally and the payload is stored as an artifact in object storage.", "operationId": "ingestEvidence", "tags": [ "Evidence" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestEvidenceRequest" } } } }, "responses": { "201": { "description": "Evidence metadata persisted and payload stored in S3" }, "400": { "description": "Payload validation failed" }, "401": { "description": "Machine authentication failed" }, "403": { "description": "Collector cannot write evidence for the project" } } } }, "/ingest/evidence/batch": { "post": { "summary": "Ingest multiple evidence payloads", "description": "Atomic batch ingest. The API persists evidence metadata for all records in the batch or for none of them. If validation or processing fails for any item, no evidence metadata from the batch is persisted.", "operationId": "ingestEvidenceBatch", "tags": [ "Evidence" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchIngestEvidenceRequest" } } } }, "responses": { "201": { "description": "All evidence metadata records in the batch were persisted and their payloads were stored." }, "400": { "description": "Batch validation or processing failed. No evidence metadata from the batch was persisted." }, "401": { "description": "Machine authentication failed" }, "403": { "description": "Collector cannot write evidence for the project. No evidence metadata from the batch was persisted." } } } } } }