# Data API

This guide provides detailed information on using the slaOS direct data ingestion API (Data API). It covers authentication, request format, field descriptions, and best practices for submitting data to slaOS.

{% hint style="info" %}
*Need help troubleshooting the Data API?* Contact us at <hello@rated.co> for consultation.
{% endhint %}

## Ingestion Endpoint

To send events to slaOS, you need to use the following endpoint:

<pre><code><strong>https://api.rated.co/v1/ingest/{ingestion_id}/{ingestion_key}
</strong></code></pre>

### **Understanding `ingestion_id` and `ingestion_key`**

* **`ingestion_id`**: A unique identifier for your slaOS project. This value is specific to your organization and is used to identify the source of the data being ingested.
* **`ingestion_key`**: A secret key that is also specific to your organization and tied to your data ingestion activities. This key works in tandem with the `ingestion_id` to authenticate your data submissions.

To find the **Ingestion Key** and **ID** in the UI, navigate to **Settings** and then select **General (Organization)**. You can access this by going to this [link](https://app.rated.co/settings/general).&#x20;

{% hint style="warning" %}
It’s important to note that the `ingestion_key` is **not** an API key or bearer token—it does not provide access to other slaOS functionalities and cannot be used to retrieve or manipulate data outside of the ingestion endpoint.
{% endhint %}

### **Additional security Considerations**

1. **Refreshing the Ingestion Key**: You can refresh your ingestion key through the slaOS UI if you suspect it has been compromised (Settings -> General)
2. **HTTPS**: Always use HTTPS to encrypt data in transit.

## Request Format

The API accepts JSON payloads. Here's an example of a valid request:

{% tabs %}
{% tab title="Single event" %}

```json
{
  "organization_id": "cust_12345",
  "key": "api_requests",
  "timestamp": "2024-08-15T10:30:45Z",
  "values": {
    "status_code": 200,
    "response_time": 0.145
  },
  "idempotency_key": "req_abc123"
}
```

{% endtab %}

{% tab title="Batch event" %}

<pre class="language-json"><code class="lang-json">[
<strong>  {
</strong>    "organization_id": "cust_12345",
    "key": "api_requests",
    "timestamp": "2024-08-15T10:30:45Z",
    "values": {
      "status_code": 200,
      "response_time": 0.145
    },
    "idempotency_key": "req_abc123"
  },
  {
    "organization_id": "cust_12345",
    "key": "api_requests",
    "timestamp": "2024-08-15T10:31:45Z",
    "values": {
      "status_code": 200,
      "response_time": 0.45
    },
    "idempotency_key": "req_def456"
  }
]
</code></pre>

{% endtab %}
{% endtabs %}

{% hint style="info" %}
The API accepts JSON payloads where the body can include either a single event or a list of events.
{% endhint %}

### Field Descriptions

1. **organization\_id** (*string*, required)
   * Unique identifier for the **customer** or **vendor** associated with this event.&#x20;
   * See [Prerequisites](/onboarding-your-data/prerequisites.md) for a refresher of the different uses of `organization_id`.
2. **key** (*string*, required)
   * A unique identifier for the type of event or metric being recorded.
   * This is not a service name, but rather a metric identifier. You can have multiple metrics for a single service, product, or project.
   * Example: "api\_requests", "database\_queries", "order\_processing"
3. **timestamp** (*string*, required)
   * The time the event occurred.
   * Accepted formats:
     * ISO 8601: `YYYY-MM-DD[T]HH:MM[:SS[.ffffff]][Z or [±]HH[:]MM]`
     * Unix timestamp (as a string)
4. **values** (*object*, required)
   * Key-value pairs representing the metrics for this event.
   * Keys are metric names, values are the corresponding measurements.
   * Value types are dynamically derived from the first payload sent under the same `key`.  However, only timestamps, strings, floats, and integers are supported.
5. **idempotency\_key** (*string*, optional)
   * Idempotency key, a unique identifier for this specific event.
   * Used for deduplication if the same event is sent multiple times.

### Limitations

* The total size of each event payload should not exceed 200KB.
* There are no specific restrictions on the number or types of key/value pairs in the `values` object.

## Ingestion endpoint example&#x20;

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST https://your-slaos-domain.com/v1/ingest/61dcde60-f40a-4a55-a303-911f2c2c4def/n3K9y3NiaOXVnw6deLQ5AQ \
     -H 'Content-Type: application/json' \
     -d '{
       "organization_id": "cust_12345",
       "key": "api_requests",
       "timestamp": "'"$(date -u +"%Y-%m-%dT%H:%M:%SZ")"'",
       "values": {
         "status_code": 200,
         "response_time": 0.145
       },
       "local_identifier": "req_abc123"
     }'
```

{% endtab %}

{% tab title="Python" %}

```bash
import httpx
import json
from datetime import datetime

url = "https://your-slaos-domain.com/v1/ingest/your-ingestion-id/your-ingestion-key"
payload = {
    "organization_id": "cust_12345",
    "key": "api_requests",
    "timestamp": datetime.utcnow().isoformat() + "Z",
    "values": {
        "status_code": 200,
        "response_time": 0.145
    },
    "local_identifier": "req_abc123"
}

headers = {"Content-Type": "application/json"}

with httpx.Client() as client:
    response = client.post(url, json=payload, headers=headers)
    print(f"Status Code: {response.status_code}")
    print(f"Response: {response.text}")
```

{% endtab %}

{% tab title="TS/JS" %}

```typescript
import fetch from 'node-fetch';

const url = 'https://your-slaos-domain.com/v1/ingest/your-ingestion-id/your-ingestion-key';
const payload = {
    organization_id: 'cust_12345',
    key: 'api_requests',
    timestamp: new Date().toISOString(),
    values: {
        status_code: 200,
        response_time: 0.145
    },
    local_identifier: 'req_abc123'
};

const headers = { 'Content-Type': 'application/json' };

fetch(url, {
    method: 'POST',
    body: JSON.stringify(payload),
    headers: headers
})
.then(response => response.text())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
```

{% endtab %}
{% endtabs %}

## Best Practices and Considerations

1. **Consistency in `key` usage**: Use consistent `key` values for similar types of events to ensure proper aggregation and analysis in slaOS.
2. **Timestamp accuracy**: Ensure that the `timestamp` is as accurate as possible to the time the event occurred.
3. **Deduplication**: Use the `local_identifier` field to prevent duplicate event processing if you're unsure about the success of a previous submission.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.rated.co/onboarding-your-data/data-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.