API · Integrations

Integrations forward a project's events to your SIEM or log pipeline. Forwarding has two parts, the same two the dashboard shows under Integrations:

  • An integration is a credential: a provider, an endpoint, and an optional token. It belongs to your account and is defined once. (The dashboard calls it a connection.)
  • A destination switches an integration on for one project, with optional per-project overrides.

Every endpoint on this page authenticates with a personal access token.

Finding your account ID

Integration endpoints are addressed by account. Your account ID is the account_id on any of your projects, so you need at least one project first:

ACCOUNT_ID=$(curl -s https://api.everscribe.io/v1/projects \
  -H "Authorization: Bearer $EVERSCRIBE_PAT" | jq -r '.projects[0].account_id')

The integration object

{
  "id": "e2b9c4f7-1a3d-4b8e-9f60-7c2d5a0e1b94",
  "account_id": "a8e3f1c2-7b4d-4e2a-9c5f-6d1b0e8a3f47",
  "name": "Splunk prod",
  "kind": "splunk_hec",
  "endpoint": "https://splunk.example.com:8088/services/collector",
  "has_token": true,
  "options": { "index": "audit", "sourcetype": "everscribe", "team": "payments" },
  "created_at": "2026-10-30T14:10:27.903Z",
  "updated_at": "2026-10-30T14:10:27.903Z"
}
Field Description
id Integration ID (UUID).
name Your label, unique within the account.
kind The provider. See Kinds.
endpoint Where events are sent.
has_token Whether a token is stored. The token itself is never returned.
options Key/value pairs with string values. See Options.

Kinds

kind Provider Token
webhook Generic JSON over HTTPS. The token is sent as Authorization: Bearer <token>, or raw in the header named by the auth_header option. optional
syslog RFC 5424 syslog with a CEF payload. not allowed
splunk_hec Splunk HTTP Event Collector. required
datadog Datadog Logs intake. required
sentinel Microsoft Sentinel (Azure Monitor / Log Analytics). required
elastic Elasticsearch _bulk API. required

Options

Some option keys configure the provider; every other key is metadata added to each forwarded event.

kind Provider settings
splunk_hec index, sourcetype, source
datadog service, ddtags
elastic index
sentinel stream
webhook auth_header
syslog protocol

In the example above, index and sourcetype go to Splunk as settings and team: payments is added to every event. Values must be strings; other types are stored but dropped when events are forwarded.

List integrations

GET /v1/accounts/{id}/integrations

Requires the account owner. Returns {"integrations": [...]}.

curl https://api.everscribe.io/v1/accounts/$ACCOUNT_ID/integrations \
  -H "Authorization: Bearer $EVERSCRIBE_PAT"

Create an integration

POST /v1/accounts/{id}/integrations

Requires the account owner.

Body field Required Description
name yes Label, 1 to 100 characters after trimming whitespace, unique within the account.
kind yes One of the kinds.
endpoint yes The provider's URL, or host:port for syslog. URLs must be https and can't point at a private or internal address.
token depends on kind The credential. Write-only.
options no String key/value pairs.

Returns 201 with {"integration": {...}}. The endpoint is saved as given, without being checked or contacted. A bad endpoint shows up only when you send a test event or in the destination's last_error.

curl -X POST https://api.everscribe.io/v1/accounts/$ACCOUNT_ID/integrations \
  -H "Authorization: Bearer $EVERSCRIBE_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Splunk prod",
    "kind": "splunk_hec",
    "endpoint": "https://splunk.example.com:8088/services/collector",
    "token": "'"$SPLUNK_HEC_TOKEN"'",
    "options": { "index": "audit" }
  }'
Status Body When
400 name is required / name must be 100 characters or fewer Bad name.
400 invalid integration kind Unknown kind.
400 A token is required for <kind> integrations. / syslog integrations don't use a token. Token rule for the kind broken.
402 Your plan allows N SIEM destination(s). Upgrade to add more. The account is at its plan's integration limit.
404 account not found Not your account.
409 integration name already taken Name in use.

Update an integration

PUT /v1/accounts/{id}/integrations/{iid}

Requires the account owner. Body fields: name, endpoint, token, options. The kind can't change.

PUT replaces name, endpoint, and options: send all three every time. A missing name fails with 400 name is required, and a missing endpoint or options is saved as empty. token is the exception. Leave it out to keep the stored token, or send a new one to rotate it.

Returns {"integration": {...}}. Errors match Create an integration, plus 404 integration not found.

curl -X PUT https://api.everscribe.io/v1/accounts/$ACCOUNT_ID/integrations/$INTEGRATION_ID \
  -H "Authorization: Bearer $EVERSCRIBE_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Splunk prod",
    "endpoint": "https://splunk.example.com:8088/services/collector",
    "options": { "index": "audit-v2" }
  }'

Delete an integration

DELETE /v1/accounts/{id}/integrations/{iid}

Requires the account owner. Returns 204 with no body. Forwarding stops on every project that used it, and its destinations are removed.

List a project's destinations

GET /v1/projects/{id}/destinations

Requires viewer on the project. Returns {"destinations": [...]}, ordered by integration name. Only integrations that have been set on this project appear, whether enabled or not. To see every integration the project could use, list the account's integrations.

{
  "destinations": [
    {
      "integration_id": "e2b9c4f7-1a3d-4b8e-9f60-7c2d5a0e1b94",
      "project_id": "5d1c0e7a-3f2b-4c8e-9a61-0d4f2b7c9e10",
      "enabled": true,
      "options": { "index": "billing-audit" },
      "last_delivered_at": "2026-10-30T14:21:09.774Z",
      "last_error_at": "0001-01-01T00:00:00Z",
      "integration_name": "Splunk prod",
      "kind": "splunk_hec",
      "created_at": "2026-10-30T14:12:44.310Z",
      "updated_at": "2026-10-30T14:12:44.310Z"
    }
  ]
}

last_error is a sanitized status and reason from the most recent failed delivery, and is left out when there's none. It never contains the token, endpoint, or response body.

Enable or disable a destination

PUT /v1/projects/{id}/destinations/{iid}

Requires editor on the project. {iid} is the integration ID, which must belong to the same account as the project.

Body field Required Description
enabled yes true to forward this project's events, false to stop. Leaving it out counts as false.
options no Per-project overrides, merged key by key over the integration's options.

Like the integration PUT, this replaces: options you leave out are cleared. Returns {"destination": {...}} (without integration_name and kind, which only the list includes), or 404 integration not found.

curl -X PUT https://api.everscribe.io/v1/projects/$PROJECT_ID/destinations/$INTEGRATION_ID \
  -H "Authorization: Bearer $EVERSCRIBE_PAT" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "options": {"index": "billing-audit"}}'

Forwarding only covers events recorded after a destination is enabled; history isn't replayed. Delivery is at least once, so use the event id to de-duplicate on your side.

Send a test event

POST /v1/projects/{id}/destinations/{iid}/test

Requires editor on the project. Sends one synthetic everscribe.integration.test event to the integration right away and reports what happened. The destination doesn't need to be enabled. The test uses the integration's own options; this project's overrides aren't applied.

This endpoint always returns 200 when the test ran. Check ok in the body:

{ "ok": false, "error": "egress: sink returned status 401" }
Field Description
ok true if the provider accepted the event.
error Sanitized reason when ok is false, e.g. a rejected status, a connection failure, or an endpoint that isn't https. 
curl -X POST https://api.everscribe.io/v1/projects/$PROJECT_ID/destinations/$INTEGRATION_ID/test \
  -H "Authorization: Bearer $EVERSCRIBE_PAT"