# Events API Docs

### Base URL

The base URL for making requests to the Event Collection API is:

| SANDBOX                                                                                                             | PRODUCTION                                                                                            |
| ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| [<mark style="color:orange;">https://sandbox-collection.conscent.in</mark>](https://sandbox-collection.conscent.in) | [<mark style="color:orange;">https://collections.conscent.in</mark>](https://collections.conscent.in) |

<details>

<summary>API Endpoints:</summary>

**Endpoint:** `/collect/event`

**Method:** POST

**Description:** The `/collect/event` endpoint is used to collect and store events in the system. Clients can send event data as JSON in the request body. The server will process the incoming event data and store it for further analysis.

**Request Body:**

The request body must contain a JSON object representing the event data. The JSON object can include the following properties:

* <mark style="color:orange;">**`messageBody`**</mark> (\[Event], required): An array containing one or more event objects, each representing an individual event.
* <mark style="color:orange;">**`messageheader`**</mark> (Object, optional): A key-value pair object containing additional headers for the event collection.

```
* Example Request: (HTTP request RAW) *

POST /collect/event HTTP/1.1
Host: example.com
Content-Type: application/json
{
  "messageBody": 
  [
		{
			...properties
		},
		{
			...properties
		}
  ],
  "messageHeaders": 
	        {
		        ...headers
	        }
}
```

**Response:**

* Status Code: 201 OK
* Content-Type: application/json

Example Response:

```json
[
	{
		"headers": {},
		"value": "{\"pingId\": \"c523aa41-9f0f-4fc2-bc96-5a8ff5520b78\"}" 
	}
]
```

</details>

<details>

<summary><strong>Error Handling:</strong></summary>

If there's an issue with the request or the server cannot process the event data, an appropriate error response will be returned.

**Example Error Response:**

```json
{
  "error": "Bad Request",
  "message": "invalid event type",
	"statusCode": 400
}
```

</details>

**Error Codes:**

The API may return various HTTP status codes to indicate the success or failure of a request. Here are some of the common status codes:

<table><thead><tr><th width="240">ERROR CODE</th><th>DESCRIPTION</th></tr></thead><tbody><tr><td><mark style="color:orange;">201 OK</mark></td><td>The request was successful, and the event data was collected.</td></tr><tr><td><mark style="color:orange;">400 Bad Request</mark></td><td>The request was malformed or had invalid parameters.</td></tr><tr><td><mark style="color:orange;">429 Too Many Requests</mark></td><td>The client has exceeded the rate limit for the /collect/event endpoint.</td></tr><tr><td><mark style="color:orange;">500 Internal Server Error</mark></td><td>An unexpected server error occurred.</td></tr></tbody></table>

<details>

<summary><strong>Rate Limits:</strong></summary>

To maintain fair usage and prevent abuse, rate limits are imposed on the /collect/event endpoint. If a client surpasses the permitted number of requests within a specific time window, the API will respond with a rate-limiting error.

**Example Response Headers:**

```
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1672766785
```

</details>

**Rate Limit Headers:**

<table><thead><tr><th width="229">Rate Limit Name</th><th>Description </th></tr></thead><tbody><tr><td><mark style="color:orange;">X-RateLimit-Limit</mark></td><td>The maximum number of requests allowed within the current time window.</td></tr><tr><td><mark style="color:orange;">X-RateLimit-Remaining</mark></td><td>The number of remaining requests allowed within the current time window.</td></tr><tr><td><mark style="color:orange;">X-RateLimit-Reset</mark></td><td>The time at which the rate limit will be reset (usually in UTC timestamp).</td></tr></tbody></table>


---

# 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.conscent.ai/events-api-docs.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.