> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Programmatic status

> Query real-time service health for all Truthlocks services. No authentication required.

Returns the current health status of every Truthlocks service. Use this endpoint to integrate service availability into your own dashboards, alerting pipelines, or circuit breakers.

This endpoint is served from `status.truthlocks.com`, not the main API. No authentication is required.

```http theme={null}
GET https://status.truthlocks.com/api/health
```

### Response

### Response fields

| Field                     | Type           | Description                                                                     |
| ------------------------- | -------------- | ------------------------------------------------------------------------------- |
| `status`                  | string         | Overall system health: `operational`, `degraded`, or `outage`.                  |
| `timestamp`               | string         | ISO 8601 timestamp of the check.                                                |
| `services`                | array          | Per-service health results.                                                     |
| `services[].id`           | string         | Machine-readable service identifier (e.g., `api-gateway`, `signing-service`).   |
| `services[].name`         | string         | Human-readable service name.                                                    |
| `services[].status`       | string         | Service health: `operational`, `degraded`, or `outage`.                         |
| `services[].responseTime` | number or null | Response time in milliseconds, or `null` if unreachable.                        |
| `services[].error`        | string         | Present only when the service is not operational. Describes the failure reason. |

### Status logic

* **`operational`** — all services are healthy and responding normally.
* **`degraded`** — at least one service is slow or returning errors, but none are fully down.
* **`outage`** — at least one service is completely unreachable.

### Monitored services

| Service ID             | Name             | Description                               |
| ---------------------- | ---------------- | ----------------------------------------- |
| `api-gateway`          | API Gateway      | Main API endpoint for all public requests |
| `trust-registry`       | Trust Registry   | Issuer management and governance          |
| `billing-service`      | Billing          | Subscription and payment processing       |
| `signing-service`      | Signing          | Cryptographic signing operations          |
| `attestation-service`  | Attestations     | Attestation minting and management        |
| `audit-service`        | Audit Logs       | Activity logging and compliance           |
| `transparency-log`     | Transparency Log | Cryptographic append-only log             |
| `verification-service` | Verification     | Proof bundle verification                 |

### Example: poll status from your application

```javascript theme={null}
async function checkTruthlockStatus() {
  const res = await fetch("https://status.truthlocks.com/api/health");
  const data = await res.json();

  if (data.status !== "operational") {
    console.warn(`Truthlocks is ${data.status}`);
    const issues = data.services.filter((s) => s.status !== "operational");
    issues.forEach((s) =>
      console.warn(`  ${s.name}: ${s.status} — ${s.error}`)
    );
  }

  return data;
}
```

### Example: pre-flight check before minting

```javascript theme={null}
async function mintWithStatusCheck(attestation) {
  const status = await fetch("https://status.truthlocks.com/api/health");
  const health = await status.json();

  const signingService = health.services.find(
    (s) => s.id === "signing-service"
  );
  const attestationService = health.services.find(
    (s) => s.id === "attestation-service"
  );

  if (
    signingService?.status !== "operational" ||
    attestationService?.status !== "operational"
  ) {
    throw new Error("Required services are not operational — retry later");
  }

  return client.attestations.mint(attestation);
}
```

<Note>
  This endpoint is rate-limited to prevent abuse. For continuous monitoring, poll
  no more frequently than once every 30 seconds.
</Note>


## OpenAPI

````yaml mint-openapi.yaml GET /health/status
openapi: 3.0.3
info:
  title: Truthlocks API
  description: >
    Truthlocks is a universal verification infrastructure for documents,
    credentials, and digital assets.

    This specification defines the canonical API for interacting with Truthlocks
    services.


    ## Base URLs

    - **Production**: `https://api.truthlocks.com`

    - **Sandbox**: `https://sandbox-api.truthlocks.com`


    ## Authentication

    - **API Keys**: Use `X-API-Key` header for machine-to-machine operations

    - **Bearer Tokens**: Use `Authorization: Bearer <jwt>` for user-initiated
    operations


    ## Tenant Identity

    In production, tenant identity is derived from the authenticated context
    (API key or JWT).

    The `X-Tenant-ID` header is ignored in production to prevent spoofing.
  version: 1.0.0
  contact:
    name: Truthlocks Support
    url: https://truthlocks.com/support
    email: support@truthlocks.com
servers:
  - url: https://api.truthlocks.com
    description: Production API
  - url: https://sandbox-api.truthlocks.com
    description: Sandbox Environment
security:
  - APIKey: []
tags:
  - name: Authentication
    description: API key and token management
  - name: Issuers
    description: Issuer registration and trust management
  - name: Keys
    description: Cryptographic key management for issuers
  - name: Attestations
    description: Attestation lifecycle (mint, revoke, supersede)
  - name: Verification
    description: Attestation verification and proof bundles
  - name: Governance
    description: Issuer governance workflows (admin only)
  - name: Identity
    description: Organization, user, and role management
  - name: Audit
    description: Audit event queries
  - name: Platform
    description: Platform administration (super admin only)
  - name: Platform Review
    description: Staff review workflows for issuer applications
  - name: Tenant Console
    description: Tenant profile and lifecycle endpoints
  - name: Health
    description: Service health and readiness endpoints
  - name: Risk
    description: Risk signal ingestion and fraud detection
  - name: Risk Enforcement
    description: Risk enforcement actions — block, challenge, quarantine, and configuration
  - name: Billing
    description: Billing, subscription, and addon management
  - name: Machine Identity
    description: >-
      Machine Agent Identity Protocol (MAIP) — agent registration, sessions,
      trust, witness, compliance, orchestration, and observability
externalDocs:
  description: Transparency read-only API (separate service spec)
  url: >-
    https://github.com/truthlocks/truthlock/blob/main/docs/transparency/openapi.yaml
paths:
  /health/status:
    get:
      tags:
        - Health
      summary: Programmatic status
      description: >-
        Returns real-time service health for all Truthlocks services. No
        authentication required.
      operationId: health.status
      responses:
        '200':
          description: Service health
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - operational
                      - degraded
                      - outage
                  timestamp:
                    type: string
                  services:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        status:
                          type: string
                        responseTime:
                          type: integer
                          nullable: true
components:
  securitySchemes:
    APIKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for machine-to-machine authentication

````