Libraries

Libraries for interacting with klev: You can also interact with klev via its CLI

Authentication

To interact with klev you need a token. You can get your first token by going to the dashboard (requires registration/login). Further tokens can be created either via the dashboard or through the API.

Once you've created your token, use it as part of the Authorization HTTP header:

Authorization: Bearer $KLEV_TOKEN

Resources

Lists the root resource urls. With this call you can also test your authentication token

GET /
Example request 
curl -H "Authorization: Bearer $KLEV_TOKEN" -H "Content-Type: application/json" \
  "https://api.klev.dev/"
Example response 
{
  "/": "supported paths",
  "/egress_webhook": "get/delete/status egress webhook",
  "/egress_webhooks": "list/create egress webhooks",
  "/filter": "get/delete/status filter",
  "/filters": "list/create filters",
  "/ingress_webhook": "get/delete ingress webhook",
  "/ingress_webhooks": "list/create ingress webhooks",
  "/log": "get/delete log",
  "/logs": "list/create logs",
  "/message": "post/get message",
  "/messages": "publish/consume messages",
  "/offset": "get/set/delete offset",
  "/offsets": "list offsets",
  "/token": "get/delete token",
  "/tokens": "list/create tokens"
}

Errors

When klev encounters an error, it returns it in a standartized format. It uses HTTP standard codes, to indicate what kind of error it was. Any request that results in 4xx or 5xx indicates an error, with the following body:
Error
Field Type Description
error_code string the error code, unique for this error
message string generic message describing this error
details string additional details about this particular error
Example request 
curl -H "Authorization: Bearer $KLEV_TOKEN" -H "Content-Type: application/json" \
  "https://api.klev.dev/unknown_path"
The above will return 404 Not Found with the following body:
Example response 
{
  "error": "ERR_KLEV_API_0005",
  "message": "Path not found",
  "details": "'/unknown_path' is not a valid application path"
}

Tokens

You can create tokens either via the dashboard or the API. At the time of creation, you get the token bearer TOKENID_SECRET, which you need to use in the Authoriaztion header. Once created the token can be manipulated via its id.

List tokens

Get a list of tokens in your account

GET /tokens?metadata={metadata}
Request
Field Type Description
metadata string, optional metadata to match when listing
Example request 
curl -H "Authorization: Bearer $KLEV_TOKEN" -H "Content-Type: application/json" \
  "https://api.klev.dev/tokens"
Response
Field Type Description
tokens array list of token objects
- token_id string the id of the token
- metadata string metadata of the token
- acl []string acl associated with the token
Example response 
{
  "tokens": [
    {
      "token_id": "tok_246SwnU0iPWez18XZ3x1eCQ6XmE",
      "metadata": "example token metadata"
    }
  ]
}

Add token

Adds a new token. The bearer field is only present at creation time, showing the full token as it must be used in the http Authorization header

POST /tokens
Request
Field Type Description
metadata string, optional metadata of the new token
acl []string, optional acl associated with the token
Example request 
curl -H "Authorization: Bearer $KLEV_TOKEN" -H "Content-Type: application/json" \
  -d '{"metadata": "another test token"}' \
  "https://api.klev.dev/tokens"
Response
Field Type Description
token_id string the id of the token
metadata string metadata of the token
acl []string acl associated with the token
bearer string the bearer value for the Authorization header
Example response 
{
  "token_id": "tok_24Ug3Y2u0uTlMCDAOB3ixYPP908",
  "metadata": "another test token",
  "bearer": "24Ug3Y2u0uTlMCDAOB3ixYPP908_61zAp8pjMdqzcXwtAwQVJk1KKg3RUjArX"
}

Get token

Get details about a token by id

GET /token/{token_id}
Request
Field Type Description
token_id string the id of the token
Example request 
curl -H "Authorization: Bearer $KLEV_TOKEN" -H "Content-Type: application/json" \
  "https://api.klev.dev/token/tok_24Ug3Y2u0uTlMCDAOB3ixYPP908"
Response
Field Type Description
token_id string the id of the token
metadata string metadata of the token
acl []string acl associated with the token
Example response 
{
  "token_id": "tok_24Ug3Y2u0uTlMCDAOB3ixYPP908",
  "metadata": "another test token",
}

Update token

Update a token by id

PATCH /token/{token_id}
Request
Field Type Description
token_id string the id of the token
metadata string metadata of the token
acl []string acl associated with the token
Example request 
curl -H "Authorization: Bearer $KLEV_TOKEN" -H "Content-Type: application/json" \
  -XPATCH -d '{"metadata": "real test token"}' \
  "https://api.klev.dev/token/tok_24Ug3Y2u0uTlMCDAOB3ixYPP908"
Response
Field Type Description
token_id string the id of the token
metadata string metadata of the token
acl []string acl associated with the token
Example response 
{
  "token_id": "tok_24Ug3Y2u0uTlMCDAOB3ixYPP908",
  "metadata": "real test token",
}

Delete token

Deletes a token by id

DELETE /token/{token_id}
Request
Field Type Description
token_id string the id of the token
Example request 
curl -H "Authorization: Bearer $KLEV_TOKEN" -H "Content-Type: application/json" \
  -XDELETE "https://api.klev.dev/token/tok_24Ug3Y2u0uTlMCDAOB3ixYPP908"
Response
Field Type Description
token_id string the id of the token
metadata string metadata of the token
acl []string acl associated with the token
Example response 
{
  "token_id": "tok_24Ug3Y2u0uTlMCDAOB3ixYPP908",
  "metadata": "another test token",
}

Logs

Each message in klev goes to a log.

List logs

Get a list of logs in your account

GET /logs?metadata={metadata}
Request
Field Type Description
metadata string, optional metadata to match when listing
Example request 
curl -H "Authorization: Bearer $KLEV_TOKEN" -H "Content-Type: application/json" \
  "https://api.klev.dev/logs"
Response
Field Type Description
logs array list of log object
- log_id string the id of the log
- metadata string metadata of the log
- compacting bool if set, this is a compacting log
- trim_bytes int64 if set, the system will keep the log size below `trim_bytes` by deleting old messages
- trim_seconds int64 if set, the system will delete messages older then trim_seconds
- trim_count int64 if set, the system will delete messages to keep the log under the `trim_count` specified length
- compact_seconds int64 if set, the system will delete old messages with the same key (relevant for compacting logs)
- expire_seconds int64 if set, the system will delete messages without value (relevant for compacting logs)
Example response 
{
  "logs": [
    {
      "log_id": "log_2B8Ykc57mzD3hDJsJpSKJLLcNaH",
      "metadata": "example log",
      "compacting": false
    }
  ]
}

Add log

Adds a new log, with configuration

POST /logs
Request
Field Type Description
metadata string, optional metadata of the log
compacting bool, optional if this is a compacting log
trim_bytes int64, optional if set, the system will keep the log size below `trim_bytes` by deleting old messages
trim_seconds int64, optional if set, the system will delete messages older then trim_seconds
trim_count int64, optional if set, the system will delete messages to keep the log under the `trim_count` specified length
compact_seconds int64, optional if set, the system will delete old messages with the same key (relevant for compacting logs)
expire_seconds int64, optional if set, the system will delete messages without value (relevant for compacting logs)
Example request 
curl -H "Authorization: Bearer $KLEV_TOKEN" -H "Content-Type: application/json" \
  -d '{"metadata": "example log", "trim_seconds": 86400}' \
  "https://api.klev.dev/logs"
Response
Field Type Description
log_id string the id of the log
metadata string metadata of the log
compacting bool if this is a compacting log
trim_bytes int64 if set, the system will keep the log size below `trim_bytes` by deleting old messages
trim_seconds int64 if set, the system will delete messages older then trim_seconds
trim_count int64 if set, the system will delete messages to keep the log under the `trim_count` specified length
compact_seconds int64 if set, the system will delete old messages with the same key (relevant for compacting logs)
expire_seconds int64 if set, the system will delete messages without value (relevant for compacting logs)
Example response 
{
  "log_id": "log_2B9toDrfgPLmOpcrGLDkVcdNM7t",
  "metadata": "example log",
  "compacting": false,
  "trim_seconds": 86400
}

Get log

Get details about a log by id

GET /log/{log_id}
Request
Field Type Description
log_id string the id of the log
Example request 
curl -H "Authorization: Bearer $KLEV_TOKEN" -H "Content-Type: application/json" \
  "https://api.klev.dev/log/log_2B9toDrfgPLmOpcrGLDkVcdNM7t"
Response
Field Type Description
log_id string the id of the log
metadata string metadata of the log
compacting bool if this is a compacting log
trim_bytes int64 if set, the system will keep the log size below `trim_bytes` by deleting old messages
trim_seconds int64 if set, the system will delete messages older then trim_seconds
trim_count int64 if set, the system will delete messages to keep the log under the `trim_count` specified length
compact_seconds int64 if set, the system will delete old messages with the same key (relevant for compacting logs)
expire_seconds int64 if set, the system will delete messages without value (relevant for compacting logs)
Example response 
{
  "log_id": "log_2B9toDrfgPLmOpcrGLDkVcdNM7t",
  "metadata": "example log",
  "compacting": false,
  "trim_seconds": 86400
}

Update log

Updates a log

PATCH /log/{log_id}
Request
Field Type Description
log_id string the id of the log
metadata string, optional metadata of the log
trim_bytes int64, optional if set, the system will keep the log size below `trim_bytes` by deleting old messages
trim_seconds int64, optional if set, the system will delete messages older then trim_seconds
trim_count int64, optional if set, the system will delete messages to keep the log under the `trim_count` specified length
compact_seconds int64, optional if set, the system will delete old messages with the same key (relevant for compacting logs)
expire_seconds int64, optional if set, the system will delete messages without value (relevant for compacting logs)
Example request 
curl -H "Authorization: Bearer $KLEV_TOKEN" -H "Content-Type: application/json" \
  -XPATCH -d '{"metadata": "another example log"}' \
  "https://api.klev.dev/log/log_2B9toDrfgPLmOpcrGLDkVcdNM7t"
Response
Field Type Description
log_id string the id of the log
metadata string metadata of the log
compacting bool if this is a compacting log
trim_bytes int64 if set, the system will keep the log size below `trim_bytes` by deleting old messages
trim_seconds int64 if set, the system will delete messages older then trim_seconds
trim_count int64 if set, the system will delete messages to keep the log under the `trim_count` specified length
compact_seconds int64 if set, the system will delete old messages with the same key (relevant for compacting logs)
expire_seconds int64 if set, the system will delete messages without value (relevant for compacting logs)
Example response 
{
  "log_id": "log_2B9toDrfgPLmOpcrGLDkVcdNM7t",
  "metadata": "another example log",
  "compacting": false,
  "trim_seconds": 86400
}

Delete log

Deletes a log by id. Also deletes all messages in that log

DELETE /log/{log_id}
Request
Field Type Description
log_id string the id of the log
Example request 
curl -H "Authorization: Bearer $KLEV_TOKEN" -H "Content-Type: application/json" \
  -XDELETE "https://api.klev.dev/log/log_2B9toDrfgPLmOpcrGLDkVcdNM7t"
Response
Field Type Description
log_id string the id of the log
metadata string metadata of the log
compacting bool if this is a compacting log
trim_bytes int64 if set, the system will keep the log size below `trim_bytes` by deleting old messages
trim_seconds int64 if set, the system will delete messages older then trim_seconds
trim_count int64 if set, the system will delete messages to keep the log under the `trim_count` specified length
compact_seconds int64 if set, the system will delete old messages with the same key (relevant for compacting logs)
expire_seconds int64 if set, the system will delete messages without value (relevant for compacting logs)
Example response 
{
  "log_id": "log_2B9toDrfgPLmOpcrGLDkVcdNM7t",
  "metadata": "example log",
  "compacting": false,
  "trim_seconds": 86400
}

Messages

Publish messages

Published messages to a log. Offsets are assigned in order of messages, the message time is assigned when the messages is presisted.

POST /messages/{log_id}
Request
Field Type Description
encoding string, optional the encoding used to turn the key/value into a byte data. empty (interpreted as 'string'), 'string', or 'base64'
messages array an array of message objects to publish
- time int64, optional the time of the message, UTC micro seconds. missing time is set to the server's current time.
- key string, optional the key of the message, encoded according 'encoding'. missing key is interpreted as nil
- value string, optional the value of the message, encoded according 'encoding'. missing value is interpreted as nil
Example request 
curl -H "Authorization: Bearer $KLEV_TOKEN" -H "Content-Type: application/json" \
  -d '{"encoding": "string", "messages": [{"key": "hello world"}]}' \
  "https://api.klev.dev/messages/log_2B9ua9eEPvoMfpu18NoovQXyQiI"
Response
Field Type Description
next_offset int64 the offset that the next message will have on the log
Example response 
{
  "next_offset": 1
}

Consume messages

Consumes messages from the log, starting with a given offset

GET /messages/{log_id}?offset={offset}&offset_id={offset_id}&len={len}&poll={poll_ms}&encoding={encoding}
Request
Field Type Description
offset int64, optional the starting offset, missing or -1 is interpreted as the end of the log, -2 for the start of the log
offset_id string, optional the offset id to use to resolve the starting offset. Only one of 'offset' and 'offset_id' can be set
poll int32, optional how long (in ms) to wait for new messages to arrive if offset is at the end of the log. defaults to no wait (0ms).
len int32, optional how many messages to return. missing value defaults to 10
encoding string, optional the encoding used to turn the key/value into a byte data. empty (interpreted as 'string'), 'string', or 'base64'
Example request 
curl -H "Authorization: Bearer $KLEV_TOKEN" -H "Content-Type: application/json" \
  "https://api.klev.dev/messages/log_2B9ua9eEPvoMfpu18NoovQXyQiI"
Response
Field Type Description
next_offset int64 the offset to use for the next consume
encoding string the encoding used to represent key/value, 'string' or 'base64'
messages array array of message objects
- offset int64 the offset of the message
- time int64 the time of the message, UTC micro seconds
- key string the message key, omitted if nil
- value string the message value, omitted if nil
Example response 
{
  "next_offset": 1,
  "encoding": "string",
  "messages": [
    {
      "offset": 0,
      "time": 1670598756024123,
      "key": "hello world"
    }
  ]
}

Post message

Publishes a single message to the log

POST /message/{log_id}
Request
Field Type Description
encoding string, optional the encoding used to turn the key/value into a byte data. empty (interpreted as 'string'), 'string', or 'base64'
time int64, optional the time of the message, UTC micro seconds. missing time is set to the server's current time.
key string, optional the key of the message, encoded according 'encoding'. missing key is interpreted as nil
value string, optional the value of the message, encoded according 'encoding'. missing value is interpreted as nil
Example request 
curl -H "Authorization: Bearer $KLEV_TOKEN" -H "Content-Type: application/json" \
  -d '{"encoding": "string", "key": "hello world"}' \
  "https://api.klev.dev/message/log_2B9ua9eEPvoMfpu18NoovQXyQiI"
Response
Field Type Description
next_offset int64 the offset that the next message will have on the log
Example response 
{
  "next_offset": 2
}

Get message by offset

Gets a message from the log based on the offset. If offset is not found, tries to return the message on the next available offset

GET /message/{log_id}?offset={offset}&encoding={encoding}
Request
Field Type Description
offset int64, optional the offset of the message, missing or -1 is interpreted as the end of the log, -2 for the start of the log
encoding string, optional the encoding used to turn the key/value into a byte data. empty (interpreted as 'string'), 'string', or 'base64'
Example request 
curl -H "Authorization: Bearer $KLEV_TOKEN" -H "Content-Type: application/json" \
  "https://api.klev.dev/message/log_2B9ua9eEPvoMfpu18NoovQXyQiI"
Response
Field Type Description
encoding string the encoding used to represent key/value, 'string' or 'base64'
offset int64 the actual offset of the message
time int64 the time of the message, UTC micro seconds
key string the message key, omitted if nil
value string the message value, omitted if nil
Example response 
{
  "encoding": "string",
  "offset": 0,
  "time": 1670598756024123,
  "key": "hello world"
}

Get message by key (get)

Gets a message from the log based on the key. If there are multiple messages with the same key, it returns the one with the higest offset

GET /message/{log_id}/key?key={key}&encoding={encoding}
Request
Field Type Description
key string, optional the key of the message, encoded according 'encoding'. missing key is interpreted as nil
encoding string, optional the encoding used to turn the key/value into a byte data. empty (interpreted as 'string'), 'string', or 'base64'
Example request 
curl -H "Authorization: Bearer $KLEV_TOKEN" -H "Content-Type: application/json" \
  "https://api.klev.dev/message/log_2B9ua9eEPvoMfpu18NoovQXyQiI/key?key=hello+world"
Response
Field Type Description
encoding string the encoding used to represent key/value, 'string' or 'base64'
offset int64 the actual offset of the message
time int64 the time of the message, UTC micro seconds
key string the message key, omitted if nil
value string the message value, omitted if nil
Example response 
{
  "encoding": "string",
  "offset": 0,
  "time": 1670598756024123,
  "key": "hello world"
}

Get message by key (post)

Gets a message from the log based on the key. If there are multiple messages with the same key, it returns the one with the higest offset

POST /message/{log_id}/key
Request
Field Type Description
encoding string, optional the encoding used to turn the key/value into a byte data. empty (interpreted as 'string'), 'string', or 'base64'
key string, optional the key of the message, encoded according 'encoding'. missing key is interpreted as nil
Example request 
curl -H "Authorization: Bearer $KLEV_TOKEN" -H "Content-Type: application/json" \
  -d '{"encoding": "string", "key": "hello world"}' \
  "https://api.klev.dev/message/log_2B9ua9eEPvoMfpu18NoovQXyQiI/key"
Response
Field Type Description
encoding string the encoding used to represent key/value, 'string' or 'base64'
offset int64 the actual offset of the message
time int64 the time of the message, UTC micro seconds
key string the message key, omitted if nil
value string the message value, omitted if nil
Example response 
{
  "encoding": "string",
  "offset": 0,
  "time": 1670598756024123,
  "key": "hello world"
}

Offsets

Offsets are a way to mark certian positions in the log that later can be used to consuming messages.

List offsets

Get a list of offsets in your account

GET /offsets?log_id={log_id}&metadata={metadata}
Request
Field Type Description
log_id string, optional log id to match when listing
metadata string, optional metadata to match when listing
Example request 
curl -H "Authorization: Bearer $KLEV_TOKEN" -H "Content-Type: application/json" \
  "https://api.klev.dev/offsets"
Response
Field Type Description
offsets array list of offset objects
- offset_id string the id of the offset
- log_id string the log id associated with the offset
- metadata string metadata of the offset
- value int64 the stored value for this offset
- value_metadata string the metadata associated with this value
Example response 
{
  "offsets": [
    {
      "offset_id": "off_246SwnU0iPWez18XZ3x1eCQ6XmE",
      "log_id": "log_2B8Ykc57mzD3hDJsJpSKJLLcNaH",
      "metadata": "example offset metadata",
      "value": 10,
      "value_metadata": "example log offset value metadata",
    }
  ]
}

Add offset

Adds a new offset, with configuration. The value of the offset is pointing to the end of the log (-2)

POST /offsets
Request
Field Type Description
log_id string the log id associated with this offset
metadata string, optional metadata of the offset
Example request 
curl -H "Authorization: Bearer $KLEV_TOKEN" -H "Content-Type: application/json" \
  -d '{"log_id": "log_2B8Ykc57mzD3hDJsJpSKJLLcNaH", "metadata": "example offset metadata"}' \
  "https://api.klev.dev/offsets"
Response
Field Type Description
offset_id string the id of the offset
log_id string the log id associated with the offset
metadata string metadata of the offset
value int64 the stored value for this offset
value_metadata string the metadata associated with this value
Example response 
{
  "offset_id": "off_246SwnU0iPWez18XZ3x1eCQ6XmE",
  "log_id": "log_2B8Ykc57mzD3hDJsJpSKJLLcNaH",
  "metadata": "example offset metadata",
  "value": -1,
  "value_metadata": "",
}

Get offset

Get details about an offset by id

GET /offset/{offset_id}
Request
Field Type Description
offset_id string the id of the offset
Example request 
curl -H "Authorization: Bearer $KLEV_TOKEN" -H "Content-Type: application/json" \
  "https://api.klev.dev/offset/off_246SwnU0iPWez18XZ3x1eCQ6XmE"
Response
Field Type Description
offset_id string the id of the offset
log_id string the log id associated with the offset
metadata string metadata of the offset
value int64 the stored value for this offset
value_metadata string the metadata associated with this value
Example response 
{
  "offset_id": "off_246SwnU0iPWez18XZ3x1eCQ6XmE",
  "log_id": "log_2B8Ykc57mzD3hDJsJpSKJLLcNaH",
  "metadata": "example offset metadata",
  "value": -1,
  "value_metadata": "",
}

Update offset

Sets new value and value metadata for an offset

PATCH /offset/{offset_id}
Request
Field Type Description
offset_id string the id of the offset
metadata string, optional metadata of the offset
value int64, optional the new stored value for this offset
value_metadata string, optional the new metadata associated with this value
Example request 
curl -H "Authorization: Bearer $KLEV_TOKEN" -H "Content-Type: application/json" \
  -XPATCH -d '{"value": 10, "value_metadata": "important offset"}' \
  "https://api.klev.dev/offset/off_246SwnU0iPWez18XZ3x1eCQ6XmE"
Response
Field Type Description
offset_id string the id of the offset
log_id string the log id associated with the offset
metadata string metadata of the offset
value int64 the stored value for this offset
value_metadata string the metadata associated with this value
Example response 
{
  "offset_id": "off_246SwnU0iPWez18XZ3x1eCQ6XmE",
  "log_id": "log_2B8Ykc57mzD3hDJsJpSKJLLcNaH",
  "metadata": "example offset metadata",
  "value": 10,
  "value_metadata": "important offset",
}

Delete offset

Deletes an offset by id

DELETE /offset/{offset_id}
Request
Field Type Description
offset_id string the id of the offset
Example request 
curl -H "Authorization: Bearer $KLEV_TOKEN" -H "Content-Type: application/json" \
  -XDELETE "https://api.klev.dev/offset/off_246SwnU0iPWez18XZ3x1eCQ6XmE"
Response
Field Type Description
offset_id string the id of the offset
log_id string the log id associated with the offset
metadata string metadata of the offset
value int64 the stored value for this offset
value_metadata string the metadata associated with this value
Example response 
{
  "offset_id": "off_246SwnU0iPWez18XZ3x1eCQ6XmE",
  "log_id": "log_2B8Ykc57mzD3hDJsJpSKJLLcNaH",
  "metadata": "example offset metadata",
  "value": 10,
  "value_metadata": "important offset",
}

Ingress webhooks

Ingress webhooks are a way to ingest external events, verify their origin and publish them to a log.

List ingress webhooks

Get a list of ingress webhooks in your account

GET /ingress_webhooks?metadata={metadata}
Request
Field Type Description
metadata string, optional if present, the server will return only webhooks matching this metadata
Example request 
curl -H "Authorization: Bearer $KLEV_TOKEN" -H "Content-Type: application/json" \
  "https://api.klev.dev/ingress_webhooks"
Response
Field Type Description
ingress_webhooks array list of ingress webhook objects
- webhook_id string the id of the webhook
- metadata string metadata about the webhook
- log_id string the id of the target log to publish events
- type string the type/source of the webhook
Example response 
{
  "ingress_webhooks": [
    {
      "webhook_id": "iwh_2Bi9gSxk5ubV5vrAHxQ5LGsO2Gz",
      "metadata": "slack",
      "log_id": "log_2Bi9eV12kt3U1be1VNorrnuxhA9",
      "type": "slack"
    }
  ]
}

Add ingress webhook

Adds a new ingress webhook, with configuration

POST /ingress_webhooks
Request
Field Type Description
metadata string, optional metadata about the ingress webhook
log_id string the id of the target log to publish events
type string the type/source of the webhook
secret string the secret used to verify incoming events
Example request 
curl -H "Authorization: Bearer $KLEV_TOKEN" -H "Content-Type: application/json" \
  -d '{"metadata": "slack", "log_id": "log_2Bi9eV12kt3U1be1VNorrnuxhA9", "type": "slack", "secret": "yyy42231b10ezzz8abcd99yyyzzz85a5"}' \
  "https://api.klev.dev/ingress_webhooks"
Response
Field Type Description
webhook_id string the id of the webhook
metadata string metadata about the webhook
log_id string the id of the target log to publish events
type string the type/source of the webhook
Example response 
{
  "webhook_id": "iwh_2Bi9gSxk5ubV5vrAHxQ5LGsO2Gz",
  "metadata": "slack",
  "log_id": "log_2Bi9eV12kt3U1be1VNorrnuxhA9",
  "type": "slack"
}

Get ingress webhook

Get details about an ingress webhook by id

GET /ingress_webhook/{webhook_id}
Request
Field Type Description
webhook_id string the id of the ingress webhook
Example request 
curl -H "Authorization: Bearer $KLEV_TOKEN" -H "Content-Type: application/json" \
  "https://api.klev.dev/ingress_webhook/iwh_2Bi9gSxk5ubV5vrAHxQ5LGsO2Gz"
Response
Field Type Description
webhook_id string the id of the webhook
metadata string metadata about the webhook
log_id string the id of the target log to publish events
type string the type/source of the webhook
Example response 
{
  "webhook_id": "iwh_2Bi9gSxk5ubV5vrAHxQ5LGsO2Gz",
  "metadata": "slack",
  "log_id": "log_2Bi9eV12kt3U1be1VNorrnuxhA9",
  "type": "slack"
}

Update ingress webhook

Update an ingress webhook

PATCH /ingress_webhook/{webhook_id}
Request
Field Type Description
webhook_id string the id of the ingress webhook
metadata string, optional metadata about the ingress webhook
secret string, optional the secret used to verify incoming events
Example request 
curl -H "Authorization: Bearer $KLEV_TOKEN" -H "Content-Type: application/json" \
  -XPATCH -d '{"metadata": "new slack", "secret": "yyy42231b10ezzz8abcd99yyyzzz85a5"}' \
  "https://api.klev.dev/ingress_webhook/iwh_2Bi9gSxk5ubV5vrAHxQ5LGsO2Gz"
Response
Field Type Description
webhook_id string the id of the webhook
metadata string metadata about the webhook
log_id string the id of the target log to publish events
type string the type/source of the webhook
Example response 
{
  "webhook_id": "iwh_2Bi9gSxk5ubV5vrAHxQ5LGsO2Gz",
  "metadata": "new slack",
  "log_id": "log_2Bi9eV12kt3U1be1VNorrnuxhA9",
  "type": "slack"
}

Delete ingress webhook

Deletes an ingress webhook by id

DELETE /ingress_webhook/{webhook_id}
Request
Field Type Description
webhook_id string the id of the ingress webhook
Example request 
curl -H "Authorization: Bearer $KLEV_TOKEN" -H "Content-Type: application/json" \
  -XDELETE "https://api.klev.dev/ingress_webhook/iwh_2Bi9gSxk5ubV5vrAHxQ5LGsO2Gz"
Response
Field Type Description
webhook_id string the id of the webhook
metadata string metadata about the webhook
log_id string the id of the target log to publish events
type string the type/source of the webhook
Example response 
{
  "webhook_id": "iwh_2Bi9gSxk5ubV5vrAHxQ5LGsO2Gz",
  "metadata": "slack",
  "log_id": "log_2Bi9eV12kt3U1be1VNorrnuxhA9",
  "type": "slack"
}

Egress webhooks

Egress webhooks are a way to send events to an external system, originating a log.

List egress webhooks

Get a list of egress webhooks in your account

GET /egress_webhooks?metadata={metadata}
Request
Field Type Description
metadata string, optional if present, the server will return only webhooks matching this metadata
Example request 
curl -H "Authorization: Bearer $KLEV_TOKEN" -H "Content-Type: application/json" \
  "https://api.klev.dev/egress_webhooks"
Response
Field Type Description
egress_webhooks array list of egress webhook objects
- webhook_id string the id of the webhook
- metadata string metadata about the webhook
- log_id string the id of the log that originates events
- destination string url where events will be posted
- payload string the payload of the webhook. One of 'message', 'key' or 'value'
Example response 
{
  "egress_webhooks": [
    {
      "webhook_id": "ewh_2SUth7PreMYDKgiiTEE3HlzVOba",
      "metadata": "notify",
      "log_id": "log_2NYltfAJZxUKNnsU1igUZlhjzDD",
      "destination": "https://example.com/klev_webhook",
      "payload": "message"
    }
  ]
}

Add egress webhook

Adds a new egress webhook, with configuration

POST /egress_webhooks
Request
Field Type Description
metadata string, optional metadata about the webhook
log_id string the id of the log that originates events
destination string url where events will be posted
payload string the payload of the webhook. One of 'message', 'key' or 'value'
Example request 
curl -H "Authorization: Bearer $KLEV_TOKEN" -H "Content-Type: application/json" \
  -d '{"metadata": "notify", "log_id": "log_2Bi9eV12kt3U1be1VNorrnuxhA9", "destination": "https://example.com/klev_webhook"}' \
  "https://api.klev.dev/egress_webhooks"
Response
Field Type Description
webhook_id string the id of the webhook
metadata string metadata about the webhook
log_id string the id of the log that originates events
destination string url where events will be posted
payload string the payload of the webhook. One of 'message', 'key' or 'value'
secret string the secret used to verify the events
Example response 
{
  "webhook_id": "ewh_2SUth7PreMYDKgiiTEE3HlzVOba",
  "metadata": "notify",
  "log_id": "log_2NYltfAJZxUKNnsU1igUZlhjzDD",
  "destination": "https://example.com/klev_webhook",
  "secret": "ewhsec_QAShtEPb8bVaj1MdtzQf6o6UNSS8VEGX4",
  "payload": "message"
}

Get egress webhook

Get details about an egress webhook by id

GET /egress_webhook/{webhook_id}
Request
Field Type Description
webhook_id string the id of the egress webhook
Example request 
curl -H "Authorization: Bearer $KLEV_TOKEN" -H "Content-Type: application/json" \
  "https://api.klev.dev/egress_webhook/ewh_2SUth7PreMYDKgiiTEE3HlzVOba"
Response
Field Type Description
webhook_id string the id of the webhook
metadata string metadata about the webhook
log_id string the id of the log that originates events
destination string url where events will be posted
payload string the payload of the webhook. One of 'message', 'key' or 'value'
Example response 
{
  "webhook_id": "ewh_2SUth7PreMYDKgiiTEE3HlzVOba",
  "metadata": "notify",
  "log_id": "log_2NYltfAJZxUKNnsU1igUZlhjzDD",
  "destination": "https://example.com/klev_webhook",
  "payload": "message"
}

Status egress webhook

Get egress webhook status by id

GET /egress_webhook/{webhook_id}/status
Request
Field Type Description
webhook_id string the id of the egress webhook
Example request 
curl -H "Authorization: Bearer $KLEV_TOKEN" -H "Content-Type: application/json" \
  "https://api.klev.dev/egress_webhook/ewh_2SUth7PreMYDKgiiTEE3HlzVOba/status"
Response
Field Type Description
webhook_id string the id of the webhook
active bool is this webhook active
inactive_reason string why was this webhook deactivated
available_offset int64 the last currently available offset on the source log
deliver_offset int64 offset on the last attempt to deliver
deliver_time int64 unix seconds on the last attempt to deliver
deliver_resp string server response on the last attempt to deliver
deliver_error string error received on the last attempt to deliver
next_deliver_offset int64 the offset to be delivered next
next_deliver_time int64 unix seconds for when the next delivery attempt will be
Example response 
{
  "webhook_id": "ewh_2SUth7PreMYDKgiiTEE3HlzVOba",
  "active": true,
  "available_offset": 33,
  "deliver_offset": 33,
  "deliver_time": 1690660131,
  "deliver_resp": "HTTP/1.1 200 OK\r\nContent-Length: 0\r\nDate: Sat, 29 Jul 2023 19:48:51 GMT\r\n\r\n",
  "next_deliver_offset": 34,
  "next_deliver_time": 1690660131,
}

Update egress webhook

Update an egress webhook

PATCH /egress_webhook/{webhook_id}
Request
Field Type Description
webhook_id string the id of the egress webhook
metadata string, optional metadata about the webhook
destination string, optional url where events will be posted
Example request 
curl -H "Authorization: Bearer $KLEV_TOKEN" -H "Content-Type: application/json" \
  -XPATCH -d '{"metadata": "notify another", "destination": "https://example.com/klev_webhook_new"}' \
  "https://api.klev.dev/egress_webhook/ewh_2SUth7PreMYDKgiiTEE3HlzVOba"
Response
Field Type Description
webhook_id string the id of the webhook
metadata string metadata about the webhook
log_id string the id of the log that originates events
destination string url where events will be posted
payload string the payload of the webhook. One of 'message', 'key' or 'value'
Example response 
{
  "webhook_id": "ewh_2SUth7PreMYDKgiiTEE3HlzVOba",
  "metadata": "notify another",
  "log_id": "log_2NYltfAJZxUKNnsU1igUZlhjzDD",
  "destination": "https://example.com/klev_webhook_new",
  "payload": "message"
}

Rotate egress webhook secret

Rotates the secret of an egress webhook by id

PATCH /egress_webhook/{webhook_id}/secret
Request
Field Type Description
webhook_id string the id of the egress webhook
expire_seconds int64, optional for how long the old secret will be valid (in seconds, defaults to 0)
Example request 
curl -H "Authorization: Bearer $KLEV_TOKEN" -H "Content-Type: application/json" \
  -XPATCH -d '{"expire_seconds": 600}' \
  "https://api.klev.dev/egress_webhook/ewh_2SUth7PreMYDKgiiTEE3HlzVOba/secret"
Response
Field Type Description
webhook_id string the id of the webhook
metadata string metadata about the webhook
log_id string the id of the log that originates events
destination string url where events will be posted
payload string the payload of the webhook. One of 'message', 'key' or 'value'
secret string the new secret used to verify the events
Example response 
{
  "webhook_id": "ewh_2SUth7PreMYDKgiiTEE3HlzVOba",
  "metadata": "notify",
  "log_id": "log_2NYltfAJZxUKNnsU1igUZlhjzDD",
  "destination": "https://example.com/klev_webhook",
  "secret": "ewhsec_QAShtEPb8bVaj1MdtzQf6o6UNSS8VEGX4",
  "payload": "message"
}

Delete egress webhook

Deletes an egress webhook by id

DELETE /egress_webhook/{webhook_id}
Request
Field Type Description
webhook_id string the id of the egress webhook
Example request 
curl -H "Authorization: Bearer $KLEV_TOKEN" -H "Content-Type: application/json" \
  -XDELETE "https://api.klev.dev/egress_webhook/ewh_2SUth7PreMYDKgiiTEE3HlzVOba"
Response
Field Type Description
webhook_id string the id of the webhook
metadata string metadata about the webhook
log_id string the id of the log that originates events
destination string url where events will be posted
payload string the payload of the webhook. One of 'message', 'key' or 'value'
Example response 
{
  "webhook_id": "ewh_2SUth7PreMYDKgiiTEE3HlzVOba",
  "metadata": "notify",
  "log_id": "log_2NYltfAJZxUKNnsU1igUZlhjzDD",
  "destination": "https://example.com/klev_webhook",
  "payload": "message"
}

Filters

Filters are a way to send a subset of the messages from one log to another.

List filters

Get a list of filters in your account

GET /filters?metadata={metadata}
Request
Field Type Description
metadata string, optional if present, the server will return only filters matching this metadata
Example request 
curl -H "Authorization: Bearer $KLEV_TOKEN" -H "Content-Type: application/json" \
  "https://api.klev.dev/filters"
Response
Field Type Description
filters array list of filter objects
- filter_id string the id of the filter
- metadata string metadata about the filter
- source_id string the id of the log that sources messages
- target_id string the id of the log that will receive matching messages
- expression string the cel expression for this filter
Example response 
{
  "filters": [
    {
      "filter_id": "trf_2n1UJ2HOSPniKNAGOLPtZGzCouM",
      "metadata": "even",
      "source_id": "log_2n1UD8T92MquWSrKsj9OMzERKsC",
      "target_id": "log_2n1UE5Tx8wDR8JLAePNyEM6YmPy",
      "expression": "offset % 2 == 0"
    }
  ]
}

Add filter

Adds a new filter, with configuration

POST /filters
Request
Field Type Description
metadata string, optional metadata about the filter
source_id string the id of the log that sources messages
target_id string the id of the log that will receive matching messages
expression string the cel expression for this filter
Example request 
curl -H "Authorization: Bearer $KLEV_TOKEN" -H "Content-Type: application/json" \
  -d '{"metadata": "even", "source_id": "log_2n1UD8T92MquWSrKsj9OMzERKsC", "target_id": "log_2n1UE5Tx8wDR8JLAePNyEM6YmPy", "expression": "offset % 2 == 0"}' \
  "https://api.klev.dev/filters"
Response
Field Type Description
filter_id string the id of the filter
metadata string metadata about the filter
source_id string the id of the log that sources messages
target_id string the id of the log that will receive matching messages
expression string the cel expression for this filter
Example response 
{
  "filter_id": "trf_2n1UJ2HOSPniKNAGOLPtZGzCouM",
  "metadata": "even",
  "source_id": "log_2n1UD8T92MquWSrKsj9OMzERKsC",
  "target_id": "log_2n1UE5Tx8wDR8JLAePNyEM6YmPy",
  "expression": "offset % 2 == 0"
}

Get filter

Get details about a filter by id

GET /filter/{filter_id}
Request
Field Type Description
filter_id string the id of the filter
Example request 
curl -H "Authorization: Bearer $KLEV_TOKEN" -H "Content-Type: application/json" \
  "https://api.klev.dev/filter/trf_2n1UJ2HOSPniKNAGOLPtZGzCouM"
Response
Field Type Description
filter_id string the id of the filter
metadata string metadata about the filter
source_id string the id of the log that sources messages
target_id string the id of the log that will receive matching messages
expression string the cel expression for this filter
Example response 
{
  "filter_id": "trf_2n1UJ2HOSPniKNAGOLPtZGzCouM",
  "metadata": "even",
  "source_id": "log_2n1UD8T92MquWSrKsj9OMzERKsC",
  "target_id": "log_2n1UE5Tx8wDR8JLAePNyEM6YmPy",
  "expression": "offset % 2 == 0"
}

Status filter

Get filter status by id

GET /filter/{filter_id}/status
Request
Field Type Description
filter_id string the id of the filter
Example request 
curl -H "Authorization: Bearer $KLEV_TOKEN" -H "Content-Type: application/json" \
  "https://api.klev.dev/filter/trf_2n1UJ2HOSPniKNAGOLPtZGzCouM/status"
Response
Field Type Description
filter_id string the id of the filter
active bool is this filter active
inactive_reason string why was this filter deactivated
available_offset int64 the last currently available offset on the source log
deliver_offset int64 offset on the last attempt to deliver
deliver_time int64 unix seconds on the last attempt to deliver
deliver_error string error received on the last attempt to deliver
next_deliver_offset int64 the offset to be delivered next
next_deliver_time int64 unix seconds for when the next delivery attempt will be
Example response 
{
  "filter_id": "trf_2n1UJ2HOSPniKNAGOLPtZGzCouM",
  "active": true,
  "available_offset": 2,
  "deliver_offset": 2,
  "deliver_time": 1728140893,
  "next_deliver_offset": 3,
  "next_deliver_time": 1728140893
}

Update filter

Updates a filter

PATCH /filter/{filter_id}
Request
Field Type Description
filter_id string the id of the filter
metadata string, optional metadata about the filter
expression string, optional the cel expression for this filter
Example request 
curl -H "Authorization: Bearer $KLEV_TOKEN" -H "Content-Type: application/json" \
  -XPATCH -d '{"metadata": "odd", "expression": "offset % 2 == 1"}' \
  "https://api.klev.dev/filter/trf_2n1UJ2HOSPniKNAGOLPtZGzCouM"
Response
Field Type Description
filter_id string the id of the filter
metadata string metadata about the filter
source_id string the id of the log that sources messages
target_id string the id of the log that will receive matching messages
expression string the cel expression for this filter
Example response 
{
  "filter_id": "trf_2n1UJ2HOSPniKNAGOLPtZGzCouM",
  "metadata": "odd",
  "source_id": "log_2n1UD8T92MquWSrKsj9OMzERKsC",
  "target_id": "log_2n1UE5Tx8wDR8JLAePNyEM6YmPy",
  "expression": "offset % 2 == 1"
}

Delete filter

Deletes a filter by id

DELETE /filter/{filter_id}
Request
Field Type Description
filter_id string the id of the filter
Example request 
curl -H "Authorization: Bearer $KLEV_TOKEN" -H "Content-Type: application/json" \
  -XDELETE "https://api.klev.dev/filter/trf_2n1UJ2HOSPniKNAGOLPtZGzCouM"
Response
Field Type Description
filter_id string the id of the filter
metadata string metadata about the filter
source_id string the id of the log that sources messages
target_id string the id of the log that will receive matching messages
expression string the cel expression for this filter
Example response 
{
  "filter_id": "trf_2n1UJ2HOSPniKNAGOLPtZGzCouM",
  "metadata": "even",
  "source_id": "log_2n1UD8T92MquWSrKsj9OMzERKsC",
  "target_id": "log_2n1UE5Tx8wDR8JLAePNyEM6YmPy",
  "expression": "offset % 2 == 0"
}