> ## 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.

# Get Agent

> Retrieve full details for a specific machine agent identity

# Get Agent

`GET /v1/agents/{agentID}`

Returns the complete agent identity record for the specified agent, including cryptographic key information, current trust score, assigned scopes, delegation depth, and all metadata. The agent must belong to the authenticated tenant.

### Authentication

Requires `X-API-Key` header or Bearer JWT token. Tenant-scoped via `X-Tenant-ID`.

### Path Parameters

<ParamField path="agentID" type="string" required>
  The MAIP agent identifier (e.g., `maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH`).
</ParamField>

### Response

<ResponseField name="id" type="string">
  Internal UUID primary key.
</ResponseField>

<ResponseField name="agent_id" type="string">
  MAIP-compliant agent identifier.
</ResponseField>

<ResponseField name="tenant_id" type="string">
  UUID of the owning tenant.
</ResponseField>

<ResponseField name="agent_type" type="string">
  Agent type classification.
</ResponseField>

<ResponseField name="display_name" type="string">
  Human-readable agent name.
</ResponseField>

<ResponseField name="description" type="string">
  Agent description.
</ResponseField>

<ResponseField name="trust_level" type="string">
  Trust hierarchy level. One of: `"platform_root"`, `"verified_org"`,
  `"verified_individual"`, `"authenticated"`, `"self_asserted"`, `"anonymous"`.
</ResponseField>

<ResponseField name="trust_score" type="number">
  Numeric trust score between 0.0 and 1.0. Adjusted over time based on agent
  behavior, anomaly detection, and attestation history.
</ResponseField>

<ResponseField name="status" type="string">
  Current lifecycle status: `"active"`, `"suspended"`, or `"revoked"`.
</ResponseField>

<ResponseField name="public_key" type="string">
  Base64url-encoded Ed25519 public key for this agent.
</ResponseField>

<ResponseField name="key_id" type="string">
  Unique key identifier for receipt and attestation signature verification.
</ResponseField>

<ResponseField name="scopes" type="string[]">
  Assigned permission scopes in `resource:action` format.
</ResponseField>

<ResponseField name="metadata" type="object">
  Arbitrary metadata attached to the agent.
</ResponseField>

<ResponseField name="parent_agent_id" type="string">
  If this agent was created via delegation, the parent agent's MAIP ID.
</ResponseField>

<ResponseField name="delegation_depth" type="number">
  Position in the delegation chain (0 = root, max 8).
</ResponseField>

<ResponseField name="created_by_user_id" type="string">
  UUID of the user who registered the agent, if applicable.
</ResponseField>

<ResponseField name="compromised_at" type="string">
  ISO 8601 timestamp if the agent's key was marked compromised.
</ResponseField>

<ResponseField name="expires_at" type="string">
  Automatic expiration timestamp, if configured.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 creation timestamp.
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 last-updated timestamp.
</ResponseField>

### Example

```bash theme={null}
curl https://api.truthlocks.com/v1/agents/maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH \
  -H "X-API-Key: tl_live_..."
```


## OpenAPI

````yaml mint-openapi.yaml GET /v1/agents/{agentId}
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:
  /v1/agents/{agentId}:
    get:
      tags:
        - Machine Identity
      summary: Get Agent
      description: >-
        Returns the full agent record including keys, trust score, and session
        count.
      operationId: maip.agents.get
      parameters:
        - name: agentId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Agent identifier
      responses:
        '200':
          description: Agent details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MaipAgent'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: Agent not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
        - APIKey: []
components:
  schemas:
    MaipAgent:
      type: object
      properties:
        id:
          type: string
          format: uuid
        agent_type:
          type: string
          enum:
            - orchestrator
            - worker
            - inference
            - pipeline
            - service
            - bot
            - llm
        display_name:
          type: string
          maxLength: 256
        description:
          type: string
        status:
          type: string
          enum:
            - active
            - suspended
            - revoked
        scopes:
          type: array
          items:
            type: string
        metadata:
          type: object
          additionalProperties: true
        trust_score:
          type: number
          format: float
          minimum: 0
          maximum: 1
        public_key:
          type: string
          description: Base64-encoded public key
        session_count:
          type: integer
        keys:
          type: array
          items:
            type: object
            properties:
              kid:
                type: string
              algorithm:
                type: string
              public_key:
                type: string
              status:
                type: string
                enum:
                  - active
                  - disabled
                  - expired
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    ErrorEnvelope:
      type: object
      required:
        - code
        - message
        - http_status
      properties:
        code:
          type: string
          description: Machine-readable error code
          enum:
            - AUTH_REQUIRED
            - AUTH_INVALID
            - PERMISSION_DENIED
            - TENANT_IDENTITY_UNVERIFIED
            - NOT_FOUND
            - VALIDATION_ERROR
            - CONFLICT
            - PAYLOAD_TOO_LARGE
            - RATE_LIMIT_EXCEEDED
            - QUOTA_EXCEEDED
            - SERVICE_UNAVAILABLE
            - INTERNAL_ERROR
        message:
          type: string
          description: Human-readable error message
        http_status:
          type: integer
          description: HTTP status code
        retry_after_ms:
          type: integer
          description: Milliseconds to wait before retrying (for rate limits)
        details:
          type: object
          description: Additional error context
      example:
        code: AUTH_REQUIRED
        message: Authentication required
        http_status: 401
  securitySchemes:
    APIKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for machine-to-machine authentication

````