{ "openapi": "3.1.0", "info": { "title": "Screenata Trust API", "version": "1.0.0", "description": "Machine-readable Trust Center (trust-api/1.0). Public-tier endpoints need no authentication and return exactly what the public Trust Center page shows. Gated resources are unlocked by an approved access request whose grant token is presented as a Bearer token. Snapshots are signed with Open Evidence Signing (OES); verify with `npx oes` against `/.well-known/oes-signing`." }, "servers": [ { "url": "https://api.screenata.com/api/trust" } ], "components": { "securitySchemes": { "GrantToken": { "type": "http", "scheme": "bearer", "description": "Approved access-request token (from `GET /v1/{slug}/access-requests/{id}`)." }, "PollSecret": { "type": "http", "scheme": "bearer", "description": "Poll secret returned once by `POST /v1/{slug}/access-requests`." } }, "schemas": { "Error": { "type": "object", "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "NOT_FOUND", "FORBIDDEN", "BAD_REQUEST", "RATE_LIMITED", "CONFLICT", "NOT_AVAILABLE", "INTERNAL_ERROR" ] }, "message": { "type": "string" } } } } }, "Freshness": { "type": "object", "properties": { "effectiveFrom": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string", "enum": [ "current", "expiring", "expired", "unknown" ] }, "updatedAt": { "type": "string", "format": "date-time" } } }, "Resource": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "category": { "type": "string", "enum": [ "report", "certificate", "policy", "other" ] }, "access": { "type": "string", "enum": [ "public", "gated" ] }, "framework": { "type": [ "string", "null" ] }, "badgeLabel": { "type": [ "string", "null" ] }, "fileName": { "type": [ "string", "null" ] }, "mimeType": { "type": [ "string", "null" ] }, "freshness": { "$ref": "#/components/schemas/Freshness" }, "contentSha256": { "type": [ "string", "null" ], "description": "Filled for public resources, or under a grant." }, "sizeBytes": { "type": [ "integer", "null" ] }, "content": { "type": "string", "format": "uri" } } }, "Index": { "type": "object", "properties": { "schemaVersion": { "type": "string", "const": "trust-api/1.0" }, "generatedAt": { "type": "string", "format": "date-time" }, "publisher": { "type": "object", "properties": { "slug": { "type": "string" }, "companyName": { "type": [ "string", "null" ] }, "websiteUrl": { "type": [ "string", "null" ] }, "securityEmail": { "type": [ "string", "null" ] }, "trustStatement": { "type": [ "string", "null" ] }, "links": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string" } } } } } }, "frameworks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "auditType": { "type": "string" }, "status": { "type": "string", "enum": [ "certified", "in_audit", "in_progress", "planned" ] }, "auditor": { "type": [ "string", "null" ] }, "date": { "type": [ "string", "null" ] } } } }, "badges": { "type": "array", "items": { "type": "string" } }, "dataHandled": { "type": "array", "items": { "type": "string" } }, "counts": { "type": "object", "properties": { "resources": { "type": "integer" }, "publicResources": { "type": "integer" }, "controls": { "type": "integer" }, "subprocessors": { "type": "integer" } } }, "attestation": { "type": "object", "properties": { "available": { "type": "boolean" }, "keyDiscovery": { "type": [ "string", "null" ] } } }, "endpoints": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } } } }, "Resources": { "type": "object", "properties": { "schemaVersion": { "type": "string" }, "generatedAt": { "type": "string", "format": "date-time" }, "resources": { "type": "array", "items": { "$ref": "#/components/schemas/Resource" } } } }, "Controls": { "type": "object", "properties": { "schemaVersion": { "type": "string" }, "generatedAt": { "type": "string", "format": "date-time" }, "summary": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "total": { "type": "integer" }, "implemented": { "type": "integer" }, "inProgress": { "type": "integer" } } } }, "controls": { "type": "array", "items": { "type": "object", "properties": { "controlId": { "type": "string" }, "title": { "type": "string" }, "framework": { "type": [ "string", "null" ] }, "domain": { "type": "string" }, "status": { "type": "string", "enum": [ "implemented", "in_progress", "not_applicable", "not_started" ] } } } } } }, "Subprocessors": { "type": "object", "properties": { "schemaVersion": { "type": "string" }, "generatedAt": { "type": "string", "format": "date-time" }, "subprocessors": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "role": { "type": "string" }, "source": { "type": [ "string", "null" ] } } } } } }, "Updates": { "type": "object", "properties": { "schemaVersion": { "type": "string" }, "generatedAt": { "type": "string", "format": "date-time" }, "updates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "category": { "type": "string" }, "eventDate": { "type": "string", "format": "date-time" } } } } } }, "Attestation": { "type": "object", "description": "An Open Evidence Signing envelope over the canonical (sorted-keys, 2-space) JSON of `snapshot`. Verify: canonicalize `snapshot`, then `oes verify envelope.json --content snapshot.bytes`.", "properties": { "schemaVersion": { "type": "string" }, "envelope": { "type": "object", "description": "OES v1.0 Evidence Signing Envelope" }, "snapshot": { "type": "object", "description": "The signed snapshot (publisher, frameworks, resources + hashes, controls summary)" } } }, "AccessRequestCreate": { "type": "object", "required": [ "requesterName", "requesterEmail", "requesterSystem" ], "properties": { "requesterName": { "type": "string" }, "requesterEmail": { "type": "string", "format": "email" }, "requesterCompany": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] }, "acceptedNda": { "type": "boolean" }, "requesterSystem": { "type": "string", "description": "Identity of the calling system, e.g. \"Screenata TPRM ยท Acme\"." }, "resourceId": { "type": [ "string", "null" ], "description": "Omit for a package request covering every gated resource." } } }, "AccessRequestCreated": { "type": "object", "properties": { "requestId": { "type": "string" }, "pollSecret": { "type": "string", "description": "Returned exactly once." }, "status": { "type": "string", "const": "pending" }, "poll": { "type": "string", "format": "uri" } } }, "AccessRequestStatus": { "type": "object", "properties": { "requestId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "approved", "denied", "revoked" ] }, "reviewedAt": { "type": [ "string", "null" ], "format": "date-time" }, "grant": { "type": [ "object", "null" ], "properties": { "token": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "scope": { "oneOf": [ { "type": "string", "const": "package" }, { "type": "object", "properties": { "resourceId": { "type": "string" } } } ] } } } } } } }, "paths": { "/v1/{slug}": { "get": { "summary": "Trust Center index", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Trust Center slug (the `/trust/{slug}` path segment)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/Index" } } } } } }, "304": { "description": "Not modified (ETag)" }, "404": { "description": "Trust Center not found or not published", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{slug}/resources": { "get": { "summary": "List visible resources", "security": [ {}, { "GrantToken": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Trust Center slug (the `/trust/{slug}` path segment)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/Resources" } } } } } }, "403": { "description": "Grant invalid or expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{slug}/resources/{id}": { "get": { "summary": "One resource", "security": [ {}, { "GrantToken": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Trust Center slug (the `/trust/{slug}` path segment)." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/Resource" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{slug}/resources/{id}/content": { "get": { "summary": "Download content (302 to a short-lived URL)", "security": [ {}, { "GrantToken": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Trust Center slug (the `/trust/{slug}` path segment)." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to presigned content URL", "headers": { "X-Content-SHA256": { "schema": { "type": "string" } }, "X-Resource-Version": { "schema": { "type": "string", "format": "date-time" } } } }, "403": { "description": "Gated resource without a covering grant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{slug}/controls": { "get": { "summary": "Control coverage summary", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Trust Center slug (the `/trust/{slug}` path segment)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/Controls" } } } } } } } } }, "/v1/{slug}/subprocessors": { "get": { "summary": "Subprocessors", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Trust Center slug (the `/trust/{slug}` path segment)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/Subprocessors" } } } } } } } } }, "/v1/{slug}/updates": { "get": { "summary": "Compliance timeline", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Trust Center slug (the `/trust/{slug}` path segment)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/Updates" } } } } } } } } }, "/v1/{slug}/attestation": { "get": { "summary": "OES-signed snapshot", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Trust Center slug (the `/trust/{slug}` path segment)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/Attestation" } } } } } }, "404": { "description": "Publisher has no signing key (NOT_AVAILABLE) or Trust Center not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{slug}/access-requests": { "post": { "summary": "Request access to gated resources", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Trust Center slug (the `/trust/{slug}` path segment)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessRequestCreate" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/AccessRequestCreated" } } } } } }, "409": { "description": "A request from this requester is already pending", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{slug}/access-requests/{id}": { "get": { "summary": "Poll an access request; the grant appears once approved", "security": [ { "PollSecret": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Trust Center slug (the `/trust/{slug}` path segment)." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/AccessRequestStatus" } } } } } }, "403": { "description": "Missing poll secret", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown request or wrong secret", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }