Errors

The API uses conventional HTTP status codes and returns a consistent error object on every failure, so you can branch on error.type and surface error.message directly.

BASE URLhttps://api.agentsworklog.dev/v1

The error object

Errors always come back under a top-level error key with a machine-readable type, a human-readable message, and — for input problems — the offending param.

ERROR OBJECT

{
  "error": {
    "type": "invalid_request",
    "message": "paths must be a non-empty array.",
    "param": "paths"
  }
}

Status codes

Every response carries one of these:

Code	Meaning
`400`	Malformed request — bad JSON or a missing required field.
`401`	Missing or invalid bearer token.
`403`	The token can't access this repository.
`404`	No such object, or you can't see it.
`409`	Conflict — e.g. archiving an already-archived activity.
`422`	Well-formed but semantically invalid (e.g. a bad enum).
`429`	Rate limited — see Rate limits.
`5xx`	Something broke on our side; safe to retry with backoff.

RESPONSE 422 Unprocessable

{
  "error": {
    "type": "validation_error",
    "message": "risk must be one of low, medium, high, critical.",
    "param": "risk"
  }
}

Idempotency

Creating an activity or notable is a POST, so retries could duplicate. Send an Idempotency-Key header with a unique value per logical operation: a repeated request with the same key returns the original result instead of creating a second entry. Keys are retained for 24 hours. GET, PATCH, and archive calls are already idempotent and ignore the header.

IDEMPOTENT CREATE

curl https://api.agentsworklog.dev/v1/activities \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: 8f3c-a1b2" \
  -d '{ "branch": "feat/auth-refresh",
       "paths": ["src/auth/**"] }'