> ## Documentation Index
> Fetch the complete documentation index at: https://docs.togai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Ingest events to Togai
> This API let’s you to ingest events to your Togai account.
Events ingested using this API will be processed via associated usage meters and further via associated price plans to generate final billable value to invoice the customer
Read more about [Event Ingestion](https://docs.togai.com/docs/event-ingestion)
## Pre-Defined event types other than raw events
-
**Named License Event:** For ingesting named license related events.
-
**Schema Name:** togai-named-license
-
**Required dimensions**:
- **license\_id:** ID of the license
- **name:** Unique name of the license
-
**Required attributes**:
- **action:** Action performed on the license, supported values are
1 or -1 for add and remove respectively
-
**Usage Event:** For ingesting usage directly to usage meters.
-
**Schema Name:** togai-usage
-
**Required dimensions**:
- **usage\_meter\_id:** ID of the usage meter
-
**Required attributes**:
- **usage:** Usage Value
## OpenAPI
````yaml post /ingest
openapi: 3.0.3
info:
version: '1.0'
title: Togai Apis
contact:
email: engg@togai.com
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
description: APIs for Togai App
servers:
- description: Api endpoint
url: https://api.togai.com/
- description: Sandbox api endpoint
url: https://sandbox-api.togai.com/
security:
- bearerAuth: []
tags:
- name: Customers
description: Customer level calls
- name: Accounts
description: Account level calls
- name: Event Schemas
description: Event Schema level calls
- name: Usage Meters
description: Usage Meter level calls
- name: Price Plans
description: (DEPRECATED) Price Plan level calls
- name: PricePlanV2
description: Price Plan V2 level calls
- name: Schedules
description: Account Schedule level calls
- name: Pricing Rules
description: Pricing Rules level calls
- name: Settings
description: Settings
- name: Price Experimentation
description: Price Experimentation apis
- name: InvoiceGroups
description: Invoice Group level calls
- name: Organization
description: Organization level calls
- name: FileStorage
description: File Storage level calls
- name: Aliases
description: Alias level calls
- name: Reports
description: Report level calls
- name: ReportTemplates
description: Report Template level calls
- name: Customer Portal
description: Portal level calls
- name: Alerts
description: Alert level calls
- name: Event Management
description: APIs for getting events ingested in Togai
externalDocs:
description: docs
url: https://togai.com/docs/billing/events
- name: Metrics
description: APIs for getting Togai metrics
externalDocs:
description: docs
url: https://togai.com/docs/metrics
- name: Licenses
description: APIs for getting or updating license records in Togai
- name: Entitlements
description: APIs related to entitlements
- name: Invoices
description: Invoices API
- name: Credits
description: Credits API
- name: Wallet
description: Wallet API
- name: InvoiceTemplates
description: InvoiceTemplates API
- name: InvoiceSequence
description: InvoiceSequence API
- name: Payments
description: Payments API
- name: Authentication
description: Authentication API
externalDocs:
description: Find out more about Togai
url: https://docs.togai.com/docs
paths:
/ingest:
post:
tags:
- Event Ingestion
summary: Ingest events to Togai
description: >
This API let’s you to ingest events to your Togai account.
Events ingested using this API will be processed via associated usage
meters and further via associated price plans to generate final billable
value to invoice the customer
Read more about [Event
Ingestion](https://docs.togai.com/docs/event-ingestion)
operationId: ingest
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/IngestEventRequest'
examples:
IngestEventRequest:
$ref: '#/components/examples/IngestEventRequest'
NamedLicenseEventRequest:
$ref: '#/components/examples/NamedLicenseEventRequest'
UsageEventRequest:
$ref: '#/components/examples/UsageEventRequest'
description: >-
Request body to ingest events to Togai usage and billing management
service.
required: true
responses:
'202':
description: Successfully accepted to process all the events from payload.
content:
application/json:
schema:
$ref: '#/components/schemas/IngestEventResponse'
'400':
description: Bad request. Please check the response message for failure details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: >-
Credential "x-api-key" is not valid. Please check the response
message for failure details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: >-
Unable to process the events as the size of the event payload is
above the supported limit. Please check our docs for the api limits
- https://togai.com/docs/limits.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: >-
Request throttled. Please check the response message on the failure
details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'503':
description: Service is currently unavailable to process the request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
default:
$ref: '#/components/responses/ErrorResponse'
components:
schemas:
IngestEventRequest:
description: Payload for ingesting events
type: object
additionalProperties: false
required:
- event
properties:
event:
$ref: '#/components/schemas/Event'
IngestEventResponse:
type: object
additionalProperties: false
properties:
success:
type: boolean
example: true
statusCode:
type: integer
format: int32
name:
type: string
message:
type: string
maxLength: 500
code:
type: string
details:
type: object
ErrorResponse:
type: object
additionalProperties: false
required:
- message
properties:
message:
type: string
description: error description
maxLength: 500
Event:
description: Contents of the event
type: object
additionalProperties: false
required:
- schemaName
- timestamp
- accountId
- attributes
- dimensions
properties:
schemaName:
description: >
Name of the Event Schema.
Know more about [event
schema](https://docs.togai.com/docs/event-schemas)
type: string
minLength: 1
maxLength: 50
id:
description: >-
Togai restricts users to ingest events with same id within a period
of *45 days*. This restriction is common for [/entitled
API](/api-reference/entitlements/ingest-event-if-a-user-is-entitled-to-a-feature),
[/ingest API](/api-reference/event-ingestion/ingest-events-to-togai)
and [/ingestBatch
API](/api-reference/event-ingestion/ingest-events-to-togai-in-batch).
i.e, an id used on /ingest API will not be allowed on /ingestBatch
or /entitled APIs
type: string
maxLength: 512
example: c0b1306d-f506-43a6-856b-69221efaee6b
timestamp:
description: >-
Source time stamp of the event. This timestamp must be in ISO 8601
format.
type: string
format: date-time
example: '2022-06-15T07:30:35.123'
accountId:
description: The event will be associated with the provided account
type: string
maxLength: 512
example: 1
attributes:
description: >-
Attributes are numeric values. It can be usage metric which you push
to Togai
type: array
minItems: 0
maxItems: 10
items:
$ref: '#/components/schemas/Attribute'
dimensions:
$ref: '#/components/schemas/Dimensions'
Attribute:
description: Metric to be recorded
type: object
additionalProperties: false
required:
- name
- value
properties:
name:
description: Name of the event attribute
type: string
minLength: 1
maxLength: 50
example: message
value:
description: Value of the event attribute
type: string
pattern: ^-?\d{1,512}(\.\d+)?$
example: 100
unit:
description: >-
Unit with which the attribute value was measured. Natively supported
units - "Meters, Miles, Kilometers, Grams, Kilograms, ounces,
Pounds, Minutes, Hours, Seconds, Milliseconds, Microseconds, None".
Clients are free to add any other custom units.
type: string
minLength: 1
maxLength: 50
example: characters
Dimensions:
description: Dimensions are tags/labels associated with the events.
type: object
additionalProperties:
type: string
minLength: 1
maxLength: 200
example:
Country: India
examples:
IngestEventRequest:
summary: example event ingestion request
value:
event:
timestamp: '2022-06-15T07:30:35.123'
schemaName: travelCompletedEvent
id: c0b1306d-f506-43a6-856b-69221efaee6b
accountId: '1'
attributes:
- name: distanceTravelled
value: '50'
unit: Miles
- name: timeSpent
value: '60'
unit: Minutes
dimensions:
location: Seattle
costCenterCode: '1234'
travelType: Business
NamedLicenseEventRequest:
summary: example usage event ingestion request
value:
event:
id: id-123
timestamp: '2024-04-18T13:23:55'
accountId: sampleID
schemaName: togai-named-license
dimensions:
license_id: addon.sample.sample
name: unique_name
attributes:
- name: action
value: '1'
UsageEventRequest:
summary: example named license event ingestion request
value:
event:
id: 42162b5e-22f6-4cd3-a9d9-019ba2c485c1
timestamp: '2024-04-18T16:00:17'
accountId: customer@biswa
schemaName: togai-usage
dimensions:
usage_meter_id: um.21UFaN6gpmS.RAbFG
attributes:
- name: usage
value: '10'
responses:
ErrorResponse:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
ErrorResponse:
summary: Error message
value:
message:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: Bearer
````