> ## 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.
# Emit Event
> Emit a service observability event for auditing, alerting, and operational monitoring.
Emits a structured observability event into the MAIP event stream. Events provide a unified audit trail of all significant actions across the machine-identity service -- from agent registration and session lifecycle to trust computation and orchestration completion.
Events are persisted with tenant isolation, indexed for fast querying, and available for webhook delivery, SIEM integration, and the metrics aggregation pipeline.
### Event Types
The `event_type` field uses a dot-separated namespace. The following event types are supported:
| Category | Event Types |
| :---------------- | :------------------------------------------------------------------------------------------------------------------------------ |
| **Agent** | `agent.registered`, `agent.updated`, `agent.suspended`, `agent.revoked`, `agent.restored` |
| **Session** | `session.created`, `session.refreshed`, `session.expired`, `session.revoked` |
| **Trust** | `trust.computed`, `trust.threshold_breach`, `trust.delegation_offered`, `trust.delegation_accepted`, `trust.delegation_expired` |
| **Orchestration** | `orchestration.started`, `orchestration.completed`, `orchestration.failed`, `orchestration.timeout` |
| **Dataset** | `dataset.attested`, `dataset.lineage_updated` |
| **Model** | `model.attested`, `model.lineage_updated` |
| **Guardrail** | `guardrail.violation`, `guardrail.circuit_breaker_opened`, `guardrail.circuit_breaker_closed` |
| **Anomaly** | `anomaly.reported`, `anomaly.resolved` |
| **Kill Switch** | `killswitch.activated` |
### Authentication
API key with `events:write` scope. Alternatively, pass a Bearer JWT token in
the `Authorization` header.
Tenant identifier for multi-tenant isolation.
### Request
Dot-separated event type identifier (e.g. `agent.registered`,
`orchestration.completed`). See the event types table above.
MAIP agent identifier associated with the event, if applicable.
Identifier of the resource affected by the event (e.g. session ID,
orchestration ID, dataset ID).
Arbitrary key-value metadata providing additional context about the event.
Event severity level. Must be one of: `info`, `warn`, `error`. Defaults to
`info`.
### Response
Unique event identifier in MAIP format (`maip-evt:ULID`).
The event type emitted.
Associated agent identifier.
Associated resource identifier.
Event severity level.
ISO 8601 timestamp of event creation.
## OpenAPI
````yaml mint-openapi.yaml POST /v1/events
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 ` 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/events:
post:
tags:
- Machine Identity
summary: Emit Event
description: |
Emits a structured observability event into the MAIP event stream for
auditing, alerting, and operational monitoring.
operationId: maip.observability.events.emit
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- event_type
properties:
event_type:
type: string
description: >-
Dot-separated event type identifier (e.g. agent.registered,
orchestration.completed)
agent_id:
type: string
description: MAIP agent identifier associated with the event
resource_id:
type: string
description: Identifier of the resource affected by the event
metadata:
type: object
additionalProperties: true
description: Arbitrary key-value metadata providing additional context
severity:
type: string
enum:
- info
- warn
- error
default: info
description: Event severity level
responses:
'201':
description: Event emitted successfully
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: Unique event identifier (maip-evt:ULID)
event_type:
type: string
agent_id:
type: string
resource_id:
type: string
severity:
type: string
created_at:
type: string
format: date-time
'401':
description: Authentication required
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'422':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
security:
- APIKey: []
components:
schemas:
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
````