Logging & Ingestion

Cloud logs can be sent through the SDK or direct HTTP. Both paths land in the same resource timeline. Use ALERT for urgent operational incidents that should stand out from INFO/WARNING/ERROR traffic. To disable SDK cloud forwarding, set ALSHIVAL_CLOUD_LEVEL=NONE. For targeting, use the DevTools Resource Details page Resource URL as ALSHIVAL_RESOURCE (owned or shared).

POST /u/<username>/resources/<resource_uuid>/logs/
X-API-Key: <api_key>
Content-Type: application/json

Payload Format

{
  "logs": [
    {
      "level": "alert",
      "message": "payment queue backed up",
      "ts": "2026-02-20T00:00:00+00:00",
      "extra": {
        "queue": "payments",
        "depth": 921,
        "region": "us-central"
      }
    }
  ]
}

Examples (Python / Node.js / curl)

import alshival

alshival.configure(
    username='your_username',
    api_key='your_api_key',
    resource='https://alshival.dev/u/resource_owner_username/resources/resource_uuid/',
    cloud_level='INFO',
)

alshival.log.info('worker online')
alshival.log.alert('cpu sustained above 95%', extra={'host': 'worker-2'})

const alshival = require('@alshival.ai/alshival');

alshival.configure({
  username: 'your_username',
  apiKey: 'your_api_key',
  resource: 'https://alshival.dev/u/resource_owner_username/resources/resource_uuid/',
  cloudLevel: 'INFO',
});

alshival.log.info('worker online');
alshival.log.alert('cpu sustained above 95%', { extra: { host: 'worker-2' } });

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ALSHIVAL_API_KEY" \
  -d '{
    "logs": [
      {
        "level": "error",
        "message": "dependency timeout",
        "ts": "2026-02-20T00:00:00+00:00",
        "extra": {"dependency": "redis", "timeout_ms": 5000}
      }
    ]
  }' \
  "${ALSHIVAL_RESOURCE%/}/logs/"

Prefer SDKs for automatic payload shaping, level filtering, and MCP helper support.

Common Error Codes

• 400 invalid_json: request body is malformed JSON.
• 400 invalid_resource: username/resource UUID mismatch.
• 401 invalid_credentials: invalid or revoked API key.
• 403 forbidden: key valid but not authorized for target resource.