Create an Audit Log
Manually records an audit event. While most audit logs are created automatically by the system, this endpoint allows you to record custom events for compliance or integration purposes.
Request Body
| Parameter | Type | Required | Description |
|---|
dockId | string | Required | The dock this event belongs to |
entityType | string | Required | The type of entity (e.g., artifact, recipient, policy, group) |
entityId | string | Required | The entity ID this event relates to |
action | string | Required | The action performed: create, update, or delete |
actor | string | Optional | The user or system that performed the action |
changes | object | Optional | Object with before and after fields describing what changed |
metadata | object | Optional | Additional context for the event |
ipAddress | string | Optional | IP address of the actor |
userAgent | string | Optional | User agent string of the actor |
Example Request
curl -X POST https://api.docyard.io/v1/audit/logs \
-H "Authorization: Bearer dk_live_a1b2c3d4..." \
-H "Content-Type: application/json" \
-d '{
"dockId": "dock_01HQ3K...",
"entityType": "artifact",
"entityId": "art_01HQ3M...",
"action": "update",
"actor": "integration-service",
"changes": {
"before": { "metadata": { "status": "pending" } },
"after": { "metadata": { "status": "reviewed" } }
},
"metadata": {
"source": "external-review-system",
"reviewId": "rev-4821"
},
"ipAddress": "10.0.1.50",
"userAgent": "ReviewBot/2.0"
}'
Response
{
"id": "aud_01HQ6C...",
"dockId": "dock_01HQ3K...",
"entityType": "artifact",
"entityId": "art_01HQ3M...",
"action": "update",
"actor": "integration-service",
"changes": {
"before": { "metadata": { "status": "pending" } },
"after": { "metadata": { "status": "reviewed" } }
},
"metadata": {
"source": "external-review-system",
"reviewId": "rev-4821"
},
"ipAddress": "10.0.1.50",
"userAgent": "ReviewBot/2.0",
"createdAt": "2025-01-22T14:30:00.000Z"
}
Error Handling
| Status | Condition |
|---|
400 | Required fields (dockId, entityType, entityId, action) are missing |
400 | action is not one of create, update, or delete |
401 | Missing or invalid API key |
404 | Dock not found |
Custom audit logs are stored alongside system-generated logs and appear in all audit queries. Use the metadata field to distinguish custom events from automatic ones.
