> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getruba.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Record Events
> ### Intent
Runs the record events action.
### When to call it
Call this when your workflow reaches the point where it must record events.
### Access boundary
Authorize the request with a token that carries `events:write`.
### Successful result
A successful request returns `200`. The response schema below defines the body your integration receives.
### Operational notes
Ingest batch of events.
export const RubaSocials = () => {
if (typeof document === "undefined") {
return null;
}
const inject = () => {
const footer = document.getElementById("footer");
if (!footer || document.getElementById("ruba-socials")) {
return false;
}
const isDark = document.querySelector("html.dark") || document.querySelector('html[class*="dark"]');
const lineColor = isDark ? "#383838" : "#e8e8ed";
const iconColor = isDark ? "#8e8e93" : "#86868b";
const markColor = isDark ? "#ffffff" : "#08080c";
const hoverColor = "#0071e3";
const div = document.createElement("div");
div.id = "ruba-socials";
div.style.cssText = `display:flex;align-items:center;gap:20px;padding-top:20px;margin-top:20px;border-top:1px solid ${lineColor};width:100%`;
const logo = `Ruba`;
const spacer = ``;
const ig = ``;
const li = ``;
const x = ``;
const github = ``;
div.innerHTML = logo + spacer + ig + li + x + github;
footer.appendChild(div);
return true;
};
if (!document.documentElement.dataset.rubaSocialsObserver) {
document.documentElement.dataset.rubaSocialsObserver = "true";
const observer = new MutationObserver(() => {
if (!document.getElementById("ruba-socials")) {
inject();
}
});
observer.observe(document.body, {
childList: true,
subtree: true
});
}
setTimeout(() => {
if (!inject()) {
const interval = setInterval(() => {
if (inject()) {
clearInterval(interval);
}
}, 500);
setTimeout(() => clearInterval(interval), 10000);
}
}, 300);
return null;
};
## OpenAPI
````yaml post /v1/events/ingest
openapi: 3.1.0
info:
title: Ruba API
summary: Ruba HTTP and Webhooks API
description: '**Details:** Read the docs at https://docs.getruba.com/api-reference.'
version: 2026-04
servers:
- url: https://api.getruba.com
description: '**Details:** Production environment.'
x-speakeasy-server-id: production
- url: https://sandbox-api.getruba.com
description: '**Details:** Sandbox environment.'
x-speakeasy-server-id: sandbox
security: []
tags:
- name: public
description: >-
**Details:** Endpoints shown and documented in the Ruba API documentation
and available in our SDKs.
- name: private
description: >-
**Details:** Endpoints that should appear in the schema only in
development to generate our internal JS SDK.
paths:
/v1/events/ingest:
post:
tags:
- events
- public
summary: Record Events
description: >-
### Intent
Runs the record events action.
### When to call it
Call this when your workflow reaches the point where it must record
events.
### Access boundary
Authorize the request with a token that carries `events:write`.
### Successful result
A successful request returns `200`. The response schema below defines
the body your integration receives.
### Operational notes
Ingest batch of events.
operationId: events:ingest
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EventsIngest'
required: true
responses:
'200':
description: Request completed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/EventsIngestResponse'
'422':
description: Request validation failed
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- oidc:
- events:write
- pat:
- events:write
- oat:
- events:write
components:
schemas:
EventsIngest:
properties:
events:
items:
anyOf:
- $ref: '#/components/schemas/EventCreateCustomer'
- $ref: '#/components/schemas/EventCreateExternalCustomer'
type: array
title: Events
description: Collection of events to ingest.
type: object
required:
- events
title: EventsIngest
EventsIngestResponse:
properties:
inserted:
type: integer
title: Inserted
description: Count of events inserted.
duplicates:
type: integer
title: Duplicates
description: Count of duplicate events skipped.
default: 0
type: object
required:
- inserted
title: EventsIngestResponse
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
EventCreateCustomer:
properties:
timestamp:
type: string
format: date-time
title: Timestamp
description: Time at which the event occurred.
name:
type: string
maxLength: 128
title: Name
description: Name assigned to the event.
organization_id:
anyOf:
- type: string
format: uuid4
description: Identifier of the organization.
examples:
- 1dbfc517-0bbf-4301-9ba8-555ca42b9737
x-ruba-selector-widget:
displayProperty: name
resourceName: Organization
resourceRoot: /v1/organizations
- type: 'null'
title: Organization Id
description: >-
Identifier of the organization owning the event. **Required unless
you use an organization token.**.
external_id:
anyOf:
- type: string
- type: 'null'
title: External Id
description: >-
**External Id:** Your unique identifier for this event. Useful for
deduplication and parent-child relationships.
parent_id:
anyOf:
- type: string
- type: 'null'
title: Parent Id
description: >-
Unique identifier for the parent event. Can be either a Ruba event
ID (UUID) or an external event ID.
metadata:
$ref: '#/components/schemas/EventMetadataInput'
description: >-
Metadata map for information your integration needs to retain about
the event. Some keys like `_llm` are structured data that are
handled specially by Ruba.
The key must be a string with a maximum length of **40 characters**.
The value must be either:
* A string with a maximum length of **500 characters**
* An integer
* A floating-point number
* A boolean
You can store up to **50 key-value pairs**.
customer_id:
type: string
format: uuid4
title: Customer Id
description: >-
Identifier of the customer in your Ruba organization associated with
the event.
member_id:
anyOf:
- type: string
format: uuid4
- type: 'null'
title: Member Id
description: >-
Identifier of the member within the customer's organization who
performed the action. Used for member-level attribution in B2B.
type: object
required:
- name
- customer_id
title: EventCreateCustomer
EventCreateExternalCustomer:
properties:
timestamp:
type: string
format: date-time
title: Timestamp
description: Time at which the event occurred.
name:
type: string
maxLength: 128
title: Name
description: Name assigned to the event.
organization_id:
anyOf:
- type: string
format: uuid4
description: Identifier of the organization.
examples:
- 1dbfc517-0bbf-4301-9ba8-555ca42b9737
x-ruba-selector-widget:
displayProperty: name
resourceName: Organization
resourceRoot: /v1/organizations
- type: 'null'
title: Organization Id
description: >-
Identifier of the organization owning the event. **Required unless
you use an organization token.**.
external_id:
anyOf:
- type: string
- type: 'null'
title: External Id
description: >-
**External Id:** Your unique identifier for this event. Useful for
deduplication and parent-child relationships.
parent_id:
anyOf:
- type: string
- type: 'null'
title: Parent Id
description: >-
Unique identifier for the parent event. Can be either a Ruba event
ID (UUID) or an external event ID.
metadata:
$ref: '#/components/schemas/EventMetadataInput'
description: >-
Metadata map for information your integration needs to retain about
the event. Some keys like `_llm` are structured data that are
handled specially by Ruba.
The key must be a string with a maximum length of **40 characters**.
The value must be either:
* A string with a maximum length of **500 characters**
* An integer
* A floating-point number
* A boolean
You can store up to **50 key-value pairs**.
external_customer_id:
type: string
title: External Customer Id
description: Your system identifier for the customer connected to this event.
external_member_id:
anyOf:
- type: string
- type: 'null'
title: External Member Id
description: >-
Identifier of the member in your system within the customer's
organization who performed the action. Used for member-level
attribution in B2B.
type: object
required:
- name
- external_customer_id
title: EventCreateExternalCustomer
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
EventMetadataInput:
properties:
_cost:
$ref: '#/components/schemas/CostMetadata-Input'
_llm:
$ref: '#/components/schemas/LLMMetadata'
additionalProperties:
anyOf:
- type: string
maxLength: 500
minLength: 1
- type: integer
- type: number
- type: boolean
type: object
title: EventMetadataInput
CostMetadata-Input:
properties:
amount:
anyOf:
- type: number
- type: string
pattern: >-
^(?!^[-+.]*$)[+-]?0*(?:\d{0,5}|(?=[\d.]{1,18}0*$)\d{0,5}\.\d{0,12}0*$)
title: Amount
description: '**Amount:** Amount in cents.'
currency:
type: string
pattern: usd
title: Currency
description: '**Currency:** Currency. Currently, only `usd` is supported.'
type: object
required:
- amount
- currency
title: CostMetadata
LLMMetadata:
properties:
vendor:
type: string
title: Vendor
description: '**Vendor:** Vendor of the event.'
model:
type: string
title: Model
description: '**Model:** Model used for the event.'
prompt:
anyOf:
- type: string
- type: 'null'
title: Prompt
description: '**Prompt:** LLM prompt used for the event.'
response:
anyOf:
- type: string
- type: 'null'
title: Response
description: LLM response used for the event.
input_tokens:
type: integer
title: Input Tokens
description: Count of LLM input tokens used for the event.
cached_input_tokens:
type: integer
title: Cached Input Tokens
description: Count of LLM cached tokens that were used for the event.
output_tokens:
type: integer
title: Output Tokens
description: Count of LLM output tokens used for the event.
total_tokens:
type: integer
title: Total Tokens
description: '**Total Tokens:** Total number of LLM tokens used for the event.'
type: object
required:
- vendor
- model
- input_tokens
- output_tokens
- total_tokens
title: LLMMetadata
securitySchemes:
oidc:
type: openIdConnect
openIdConnectUrl: /.well-known/openid-configuration
pat:
type: http
description: >-
**Authentication:** You can generate a **Personal Access Token** from
your [settings](https://getruba.com/settings).
scheme: bearer
oat:
type: http
description: >-
**Authentication:** You can generate an **Organization Access Token**
from your organization's settings.
scheme: bearer
````